# Guide utilisateur — UXPER

> Version 0.7.0 : UXPER pour OpenCode, Claude Code et Cursor, avec familles de personas, priorités P0–P3 et revue visuelle multi-écrans via Chromium/Playwright en option. Licence PolyForm Noncommercial 1.0.0; chaque CLI utilise son adaptateur natif.

> **Licence :** PolyForm Noncommercial License 1.0.0. Elle n’autorise pas l’usage commercial, notamment l’usage interne par une entreprise à but lucratif. Consultez le fichier `LICENSE.txt` livré avec la release ou le texte officiel sur https://polyformproject.org/licenses/noncommercial/1.0.0 avant installation.

## À quoi sert le modèle ?

UXPER aide à examiner un site ou une application depuis plusieurs perspectives de personas. Les agents observent l’interface, confrontent leurs constats, les évaluent, puis un arbitre vérifie les éléments cités et motive ses décisions. Le résultat est une analyse exploratoire à discuter avec l’équipe, pas un test effectué auprès d’utilisateurs réels.

## Prérequis

- Node.js 20+ et npm pour installer le paquet UXPER.
- Au moins un environnement pris en charge installé : OpenCode, Claude Code ou Cursor.
- Un modèle configuré dans l’environnement choisi. Tous les rôles UXPER utilisent ce modèle.
- Un accès web disponible dans l’environnement choisi; la profondeur d’inspection dépend de ses outils et permissions.
- Pour la revue visuelle : installation optionnelle de Chromium/Playwright avec `uxper browser install --target <cible>` puis rechargement de l’environnement.
- Pour générer le PDF d’un rapport d’analyse : capacité d’export ou de rendu PDF accessible depuis le CLI. Ces outils ne sont pas installés ni simulés par la release; le PDF du guide utilisateur est fourni séparément.

## Licence d’utilisation

UXPER est distribué sous **PolyForm Noncommercial License 1.0.0**. Elle permet les usages non commerciaux et certaines utilisations personnelles ou d’organismes non commerciaux prévues par le texte. Elle n’autorise pas l’usage à des fins commerciales, y compris l’usage interne par une entreprise à but lucratif. Chaque paquet distribué contient le texte de licence. Lisez les conditions avant installation et utilisation.

## Installation

Depuis la racine du dépôt, générez l’unique paquet multi-CLI. Cette commande est identique sur Windows, macOS et Linux :

```sh
npm run release:uxper
```

Installez ensuite la commande npm. Depuis la racine du dépôt, choisissez le chemin adapté à votre terminal :

```powershell
npm install --global .\release\uxper\uxper-agents-0.7.0.tgz
```

```sh
npm install --global ./release/uxper/uxper-agents-0.7.0.tgz
```

Après téléchargement du paquet depuis la page du projet, vous pouvez aussi passer son chemin local à npm, par exemple :

```sh
npm install --global "$HOME/Downloads/uxper-agents-0.7.0.tgz"
```

Si le navigateur enregistre le fichier ailleurs, remplacez le chemin par son emplacement réel.

Depuis le répertoire du projet que vous souhaitez analyser, choisissez sa cible :

```powershell
uxper install --target opencode --scope project
uxper install --target claude-code --scope project
uxper install --target cursor --scope project
```

Pour activer Chromium et les outils Playwright MCP, utilisez la même cible que pour les agents :

```sh
uxper browser install --target opencode --scope project
uxper browser status --target opencode --scope project
```

Répétez ces commandes avec `--target claude-code` ou `--target cursor` selon le CLI utilisé. L’installation télécharge Chromium dans le cache Playwright de l’utilisateur (connexion Internet requise) et écrit la configuration propre à la cible : `.opencode/opencode.json`, `.mcp.json` pour Claude Code ou `.cursor/mcp.json`. Le téléchargement n’est pas lancé automatiquement pendant `npm install`. Pour une configuration globale, utilisez `--scope global`; Claude Code utilise alors `~/.claude.json`, Cursor `~/.cursor/mcp.json`. Si l’installation échoue, la configuration MCP n’est pas ajoutée. Sur Linux, des bibliothèques système peuvent être requises; UXPER n’exécute aucune commande privilégiée automatiquement.

L’intégration utilise le nom MCP dédié `uxper_browser` et préserve les entrées déjà configurées. Les fichiers JSONC/commentés ne sont pas réécrits; récupérez le fragment avec `uxper browser config --target <cible>`, ajoutez-le manuellement puis rechargez le CLI.

```sh
uxper browser status --target opencode --scope project
```

Pour désactiver l’intégration UXPER sans supprimer le navigateur du cache partagé :

```sh
uxper browser uninstall --target opencode --scope project
```

Pour rendre les agents disponibles dans tous les projets de l’utilisateur, choisissez aussi la cible :

```sh
uxper install --target opencode --scope global
uxper install --target claude-code --scope global
uxper install --target cursor --scope global
```

Les commandes `uxper` sont identiques sur Windows, macOS et Linux. `--scope project` écrit dans le dossier du CLI choisi; `--scope global` cible la configuration utilisateur. L’installation a été vérifiée sous Windows.

L’installateur refuse d’écraser silencieusement des fichiers différents. Comparez-les; ajoutez `--force` seulement si vous souhaitez les remplacer. Prévisualisez avec `--dry-run`. Pour retirer les fichiers d’une cible sans toucher aux fichiers modifiés : `uxper uninstall --target <cible> --scope project` ou `--scope global`.

Rechargez le CLI après l’installation : redémarrez OpenCode ou Claude Code; dans Cursor, rechargez la fenêtre ou démarrez une nouvelle conversation Agent.

## Test de fumée par CLI

Utilisez une page publique sans compte et arrêtez-vous après la validation des personas; ne soumettez aucun formulaire.

| Cible | Démarrage | Vérification rapide |
|---|---|---|
| OpenCode | `/uxper https://example.com` | Le dialogue UXPER s’ouvre; `opencode mcp list` montre `uxper_browser` connecté si l’option navigateur a été installée. |
| Claude Code | Lancer `claude`, puis `/uxper https://example.com` | `/agents` liste les sous-agents UXPER; `claude mcp list` montre `uxper_browser` si installé. Approuver le MCP de projet lorsque Claude Code le demande. |
| Cursor | Dans Agent, lancer `/uxper https://example.com` | Le skill UXPER démarre; les agents de `.cursor/agents/` sont disponibles. Vérifier `uxper_browser` dans la configuration MCP de Cursor si l’option navigateur est installée. |

Pour chaque cible, le test réussit si le dialogue demande le contexte et fait valider les personas avant l’analyse approfondie. Ce test vérifie l’installation et le démarrage, pas l’exactitude d’une revue.

## Parcours d’utilisation

1. Dans le CLI choisi, lancer `/uxper https://votre-site.fr` (ou invoquer le skill UXPER avec cette URL dans le contexte).
2. Décrire librement le contexte, l’objectif ou les questions de l’équipe.
3. Répondre aux demandes de précision du dialogue guidé.
4. Examiner les familles/catégories de publics, les tranches d’âge et le nombre de personas proposé dans chaque famille ; valider ou ajuster les profils avant l’analyse. Le modèle n’est pas limité à trois familles ni à un seul persona par famille. Par défaut, il vise deux personas par famille pertinente lorsque les différences sont utiles ; l’utilisateur peut demander deux par famille ou valider un autre nombre justifié. Aucun doublon artificiel n’est créé.
5. Laisser les personas analyser et confronter leurs constats, puis les évaluateurs les relire.
6. Examiner les décisions motivées de l’arbitre, les avis minoritaires et les désaccords persistants.
7. Contester une décision ou demander une nouvelle itération si nécessaire. La stabilisation signifie que les constats, priorités et niveaux de confiance ne changent plus substantiellement ; elle n’empêche pas une relance.
8. Consulter le rapport Markdown, le JSON et le PDF si celui-ci a pu être généré.
9. Consulter les captures liées aux constats visuels : fichiers séparés référencés dans Markdown/JSON et annexés au PDF lorsqu’il a été produit.

## Inspection visuelle et priorités

Quand le serveur `uxper_browser` est connecté et autorisé, le parcours demande une inspection distincte du rendu textuel à plusieurs formats : mobile (390×844 CSS px), tablette (768×1024) et bureau (1440×900), à adapter au service. `uxper browser status --target <cible>` vérifie Chromium et la configuration MCP. Chaque constat visuel s’appuie sur une capture réellement prise; le rapport précise l’URL, le viewport, la date et le chemin du fichier. Les captures sont conservées dans `uxper-artifacts/<mission-id>/captures/`. Les navigateurs partagés sont utilisés séquentiellement. Si le navigateur ou la capture échoue ou n’est pas autorisé, le rendu visuel est déclaré non inspecté et aucun constat visuel n’est inventé.

Les priorités sont classées : **P0 bloquante** (tâche essentielle impossible, impact important et aucun contournement raisonnable), **P1 élevée** (besoin majeur fortement bloqué, risque important ou contournement coûteux), **P2 moyenne** (friction avec contournement praticable), **P3 basse** (impact limité ou finition). Chaque niveau est justifié séparément pour le persona et pour l’équipe selon l’impact, la portée, l’urgence et les contournements. La confiance reste distincte : une preuve faible rend la priorité provisoire plutôt que d’effacer un impact potentiellement grave.

## Interactions avec le site

Les agents peuvent parcourir le site et tester les interactions réversibles. Ils demandent l’accord de l’utilisateur avant une soumission ou toute action qui pourrait envoyer des données, engager l’utilisateur ou modifier un état réel.

## Comprendre les résultats

Un constat distingue l’élément observé, son interprétation par le persona, son impact potentiel, son niveau de confiance et les hypothèses éventuelles. Les priorités et catégories sont proposées à la fois pour le persona et pour l’équipe.

Pour les offres payantes, l’analyse peut considérer les tarifs et conditions visibles, l’adéquation au profil financier validé, la valeur de l’offre dans la durée, l’existence d’un essai et les motifs possibles d’abandon. Une conclusion d’abordabilité concerne le persona considéré, pas tous les utilisateurs.

Le niveau d’étude, l’âge et la situation financière sont traités comme des caractéristiques distinctes. Les agents ne déduisent pas automatiquement le budget ou les capacités d’une personne à partir de son âge ou de son niveau d’étude.

## Mémoire entre missions

Les agents peuvent suggérer les éléments qui seraient utiles à conserver pour d’autres analyses. Rien n’est mémorisé ou réutilisé automatiquement : l’utilisateur choisit ce qu’il valide.

## Familles, variantes et genre

Une famille/catégorie représente un grand public concerné par le site (par exemple, citoyens, parents, associations ou responsables IT). Une famille peut contenir plusieurs personas individuels si leurs objectifs, rôles, expériences ou contraintes diffèrent. Les IDs individuels et de famille servent à préserver ces différences dans les constats et les rapports.

Le genre ou l’identité de genre est facultatif. Il ne doit être inclus que si la mission le rend pertinent et que cette pertinence est explicitée ; il peut rester non précisé et l’utilisateur n’est jamais invité à révéler son propre genre. Les agents ne le déduisent ni du nom ni du rôle, et n’en infèrent pas des besoins, capacités ou comportements stéréotypés. Si l’utilisateur demande une comparaison de genre, les profils sont appariés autant que possible sur les autres dimensions ; les résultats restent des hypothèses qualitatives à vérifier, pas des statistiques sur une population.

## Limites

- L’analyse ne certifie ni l’utilisabilité ni l’accessibilité du service.
- Les personas simulés ne représentent pas statistiquement une population.
- Les conclusions portent uniquement sur les éléments accessibles et observés ; les inconnues et limites doivent rester visibles.
- Les rapports servent à orienter des discussions et des recherches complémentaires, pas à remplacer des retours de personnes réelles.