fix: brainstorm infinite loop, ghost cursor, embedding ::vector cast, semantic search, billing stats, usage meter accordion

- Fix useBrainstormSocket: stable guestId via useRef, remove setState in cleanup - Fix GhostCursor: direct DOM manipulation via refs, no useState re-renders - Fix all SQL embedding queries: add ::vector cast on text columns - Fix embedding truncation to 15000 chars (under 8192 token limit) - Fix NoteEmbedding INSERT: remove non-existent updatedAt column - Fix billing page: show all quota stats in grid instead of single metric - Fix usage meter: accordion expand/collapse, per-feature detail - Fix semantic search: rebuild 103 note embeddings, ::vector cast on vectorSearch - Fix brainstorm expand/manual-idea/create: ::vector cast on embedding SQL
2026-05-16 18:50:34 +00:00
parent ee8e2bda59
commit 8c7ca69640
117 changed files with 11732 additions and 834 deletions
--- a/docs/guide-utilisateur/README.md
+++ b/docs/guide-utilisateur/README.md
@@ -0,0 +1,307 @@
+# Guide utilisateur Momento
+
+Documentation produit illustrée du SaaS **Momento** — second cerveau augmenté par l’IA (notes, recherche sémantique, agents, brainstorm collaboratif, BYOK).
+
+> **Sources internes** : ce guide synthétise le [PRD](../prd.md), les [fonctionnalités IA](../fonctionnalites-ia.md), la [doc brainstorm](../../memento-note/docs/brainstorm-documentation.md) et le [GUIDE technique](../../GUIDE.md) (installation / admin).
+
+---
+
+## Sommaire
+
+1. [Vue d’ensemble](#1-vue-densemble)
+2. [Premiers pas](#2-premiers-pas)
+3. [Page d’accueil (marketing)](#3-page-daccueil-marketing)
+4. [Espace de travail](#4-espace-de-travail)
+5. [Intelligence artificielle](#5-intelligence-artificielle)
+6. [Agents autonomes](#6-agents-autonomes)
+7. [Brainstorm radial](#7-brainstorm-radial)
+8. [Paramètres et facturation](#8-paramètres-et-facturation)
+9. [Administration](#9-administration)
+10. [Captures d’écran](#10-captures-décran)
+11. [Aller plus loin](#11-aller-plus-loin)
+
+---
+
+## 1. Vue d’ensemble
+
+Momento est une application de prise de notes qui combine :
+
+- **Organisation** : carnets, labels, grille masonry, archive, corbeille, partage.
+- **Recherche sémantique** : trouver par idée, pas seulement par mot-clé (vecteurs + plein texte).
+- **IA intégrée** : chat RAG sur vos notes, reformulation, tags et titres suggérés, Memory Echo.
+- **Agents** : Scraper, Researcher, Monitor, générateur de slides/diagrammes, agents personnalisés.
+- **Brainstorm** : canvas radial D3 en temps réel (vagues Variations / Analogies / Disruptions).
+- **BYOK** : connecter vos propres clés API (OpenAI, Anthropic, Google, etc.) pour maîtriser les coûts.
+- **Modèle commercial** : pack découverte IA, abonnements Pro / Business / Enterprise, facturation « host-pays » en session partagée.
+
+**Publics visés** : créateurs, consultants, équipes R&D, organisations qui veulent une mémoire de travail partagée et sécurisée.
+
+---
+
+## 2. Premiers pas
+
+### Créer un compte
+
+1. Ouvrir l’URL de votre instance (ex. `https://votre-domaine.com`).
+2. Cliquer sur **Get started** ou **Sign up**.
+3. Renseigner email, nom et mot de passe.
+
+![Inscription](screenshots/08-register.png)
+
+### Se connecter
+
+![Connexion](screenshots/07-login.png)
+
+En cas d’oubli : **Forgot password?** envoie un lien de réinitialisation par email (SMTP configuré côté serveur).
+
+![Mot de passe oublié](screenshots/09-forgot-password.png)
+
+### Après connexion
+
+Vous arrivez sur **l’accueil notes** (`/home`) : sidebar (carnets, navigation), zone centrale (grille ou liste de notes), actions de création.
+
+> Les captures de l’application connectée (`10-app-*.png`, etc.) nécessitent une session active. Voir [Régénérer les captures](#régénérer-les-captures).
+
+---
+
+## 3. Page d’accueil (marketing)
+
+La landing publique présente la proposition de valeur avant inscription.
+
+### Hero — second cerveau amplifié
+
+![Landing — hero](screenshots/01-landing-hero.png)
+
+Message clé : Momento relie, analyse et développe vos idées avec **6 types d’agents IA** et une **recherche sémantique** avancée. Exemple produit : *Memory Echo* qui signale un lien avec un projet passé.
+
+### Capacités IA
+
+![Landing — fonctionnalités IA](screenshots/02-landing-features.png)
+
+| Bloc | Ce que l’utilisateur y gagne |
+|------|------------------------------|
+| **Semantic Search** | Retrouver une note par le sens, pas seulement les mots exacts. |
+| **Contextual RAG Chat** | Dialoguer avec tout votre corpus (notes + web + documents). |
+| **Augmented Writing** | Reformulation, titres, tags et résumés en arrière-plan. |
+
+### Agents spécialisés
+
+![Landing — agents](screenshots/03-landing-agents.png)
+
+Six rôles mis en avant : **Scraper**, **Researcher**, **Slide Gen**, **Monitor**, **Diagram Gen**, et agents **Custom** (rôles et sources de données définis par vous).
+
+### Brainstorm — vagues de pensée
+
+![Landing — brainstorm](screenshots/04-landing-brainstorm.png)
+
+Brainstorming radial temps réel : génération par vagues, collaboration (curseurs, avatars), export sémantique vers des notes structurées.
+
+### Tarifs
+
+![Landing — tarifs](screenshots/05-landing-pricing.png)
+
+| Offre | Positionnement |
+|-------|----------------|
+| **Basic** | Découverte (notes limitées, crédits IA découverte). |
+| **Pro** | Créateurs / consultants (BYOK OpenAI/Anthropic, agents, historique étendu). |
+| **Business** | Équipes (collaborateurs, 13 fournisseurs BYOK, API). |
+| **Enterprise** | SSO/SAML, agents illimités, audit, support dédié. |
+
+### BYOK — votre propre fournisseur IA
+
+![Landing — BYOK](screenshots/06-landing-byok.png)
+
+Si vous avez déjà des clés **OpenAI**, **Anthropic** ou **Google**, vous les connectez à Momento : pas de plafond de crédits imposé par la plateforme, facturation directe chez le fournisseur, changement de provider en un clic.
+
+---
+
+## 4. Espace de travail
+
+### Notes et carnets
+
+- **Types de notes** : texte riche, checklist, Markdown, texte brut.
+- **Carnets** : regroupement thématique ; **labels** contextuels (y compris suggérés par l’IA).
+- **Vues** : grille masonry (drag-and-drop) ou onglets.
+- **Cycle de vie** : archive, corbeille, historique des versions, partage avec permissions.
+
+### Recherche
+
+Barre de recherche globale : mode **plein texte** et mode **sémantique** (embeddings). Idéal pour « retrouver cette idée sur l’architecture modulaire » sans se souvenir du titre exact.
+
+### Chat IA (`/chat`)
+
+Conversations persistées, alimentées par vos notes (RAG), avec outils : recherche de notes, lecture, recherche web, scrape. Le système peut cibler un carnet ou la note ouverte (mode Copilot).
+
+### Lab (`/lab`)
+
+Tableau blanc **Excalidraw** intégré pour schémas, mindmaps et croquis libres.
+
+---
+
+## 5. Intelligence artificielle
+
+Détail technique : [fonctionnalites-ia.md](../fonctionnalites-ia.md).
+
+### Trois fournisseurs configurables
+
+| Tier | Usage |
+|------|--------|
+| **Tags** | Tags, reformulation, suggestions de titre |
+| **Embeddings** | Recherche sémantique, Memory Echo |
+| **Chat** | Chat RAG, agents, brainstorm, vision |
+
+Chacun peut pointer vers un modèle différent (OpenAI, Ollama local, Anthropic, DeepSeek, OpenRouter, etc.).
+
+### Dans l’éditeur de note
+
+- **Suggestions de titre** (3 styles).
+- **Tags contextuels** parmi les labels du carnet ou nouveaux.
+- **Reformulation** : clarifier, raccourcir, style, grammaire, traduire.
+- **Description d’images** (vision) pour notes illustrées.
+
+### Memory Echo
+
+Détection proactive de liens entre notes (similarité vectorielle) avec explication en une phrase ; feedback pouce haut/bas pour affiner la sensibilité.
+
+### Quotas et pack découverte
+
+Indicateur de consommation IA (sidebar). À l’épuisement : proposition d’**upgrade** ou d’ajout d’une **clé BYOK** — pas de blocage brutal sans issue.
+
+---
+
+## 6. Agents autonomes
+
+Page **Agents** (`/agents`) : créer, planifier et suivre des agents.
+
+| Type | Rôle |
+|------|------|
+| **Scraper** | URLs + flux RSS → synthèse et note avec images |
+| **Researcher** | Requêtes web → note de recherche structurée |
+| **Monitor** | Surveillance d’un carnet → tendances et insights |
+| **Custom** | Rôle libre + sources optionnelles |
+| **Slide Generator** | PowerPoint ou slides HTML Reveal.js |
+| **Diagram Gen** | Diagrammes Excalidraw (mindmap, flowchart, etc.) |
+
+Planification : manuel, horaire, quotidien, hebdomadaire, mensuel (fuseau IANA).
+
+Résultats : notification in-app et par email selon configuration.
+
+---
+
+## 7. Brainstorm radial
+
+Documentation technique : [brainstorm-documentation.md](../../memento-note/docs/brainstorm-documentation.md).
+
+### Parcours type
+
+1. Saisir une **idée graine** (ou partir d’une note existante).
+2. L’IA génère **3 vagues** : Variations → Analogies → Disruptions (9 idées).
+3. Sur le **canvas D3** : zoom, drag, approfondir, rejeter, convertir en note.
+4. **Partager** la session (lien invité ; l’hôte paie les tokens en mode host-pays).
+5. **Exporter** en note structurée ou formats de présentation.
+
+### Collaboration
+
+Socket.io : curseurs en direct, déplacement de nœuds, présence des participants (host / editor / viewer).
+
+---
+
+## 8. Paramètres et facturation
+
+Accessible via l’icône paramètres (profil utilisateur).
+
+| Section | Contenu |
+|---------|---------|
+| **Profil** | Identité, email, mot de passe |
+| **Apparence** | Thème clair/sombre, langue (15 locales) |
+| **IA** | Préférences utilisateur ; clés **BYOK** personnelles (chiffrées AES-256-GCM) |
+| **Facturation** | Abonnement Stripe, usage, portail client |
+| **Données** | Export / import JSON |
+| **MCP** | Clés API pour le serveur MCP (Claude Desktop, N8N, etc.) |
+
+### BYOK côté utilisateur
+
+Coller la clé du fournisseur choisi → validation en direct → badge « mode BYOK » ; le routeur LLM bascule automatiquement sans choix manuel à chaque requête.
+
+### Facturation host-pays
+
+Dans une session brainstorm partagée, c’est l’**hôte** qui consomme le quota / la clé BYOK pour les invités — flux fluide pour les équipes.
+
+---
+
+## 9. Administration
+
+Réservé aux comptes **ADMIN** (premier email `ADMIN_EMAIL` à l’inscription ou promotion manuelle).
+
+| Zone | Rôle |
+|------|------|
+| **Utilisateurs** | Gestion des comptes et rôles |
+| **IA** | Fournisseurs système (tags, embeddings, chat), **fournisseur de secours** optionnel (erreurs 429/5xx) |
+| **Tests IA** | Valider tags et embeddings |
+| **Sécurité** | Inscription publique on/off |
+| **SMTP** | Emails transactionnels |
+
+Guide déploiement et variables : [GUIDE.md](../../GUIDE.md).
+
+---
+
+## 10. Captures d’écran
+
+| Fichier | Description |
+|---------|-------------|
+| `01-landing-hero.png` | Landing — accroche |
+| `02-landing-features.png` | Capacités IA |
+| `03-landing-agents.png` | Agents |
+| `04-landing-brainstorm.png` | Brainstorm |
+| `05-landing-pricing.png` | Tarifs |
+| `06-landing-byok.png` | BYOK |
+| `07-login.png` | Connexion |
+| `08-register.png` | Inscription |
+| `09-forgot-password.png` | Mot de passe oublié |
+| `10-app-home.png` | Accueil (connecté) |
+| `11-app-chat.png` | Chat IA |
+| `12-app-agents.png` | Agents |
+| `13-app-brainstorm.png` | Brainstorm app |
+| `14-app-lab.png` | Lab Excalidraw |
+| `15-settings-ai.png` | Paramètres IA / BYOK |
+| `16-settings-billing.png` | Facturation |
+| `17-settings-profile.png` | Profil *(si capture auth)* |
+| `18-admin-dashboard.png` | Admin *(si capture auth)* |
+
+### Régénérer les captures
+
+Depuis le dossier **`memento-note/`** (Playwright y est installé) :
+
+```bash
+cd memento-note
+npx playwright install chromium   # une seule fois
+
+# Pages publiques uniquement
+node ../docs/guide-utilisateur/capture-screenshots.mjs
+
+# + application connectée (recommandé pour 10–18)
+MOMENTO_DOC_EMAIL=votre@email.com \
+MOMENTO_DOC_PASSWORD='votre-mot-de-passe' \
+node ../docs/guide-utilisateur/capture-screenshots.mjs
+```
+
+- **URL** : par défaut lue depuis `memento-note/.env` → `NEXTAUTH_URL` (ex. `http://192.168.1.83:3000`). Surcharge : `MOMENTO_DOC_BASE_URL`.
+- En cas d’échec de connexion, les captures **01–09** sont quand même produites ; **10–18** sont ignorées.
+
+---
+
+## 11. Aller plus loin
+
+| Document | Public | Sujet |
+|----------|--------|--------|
+| [GUIDE.md](../../GUIDE.md) | Admin / DevOps | Installation, Docker, env, MCP |
+| [fonctionnalites-ia.md](../fonctionnalites-ia.md) | Produit / Dev | Détail des capacités IA |
+| [prd.md](../prd.md) | Produit | Vision, parcours, exigences |
+| [ux-design-specification.md](../ux-design-specification.md) | Design | Quotas, BYOK, RGPD |
+| [epics.md](../epics.md) | Engineering | Stories commerciales V3 |
+| [brainstorm-documentation.md](../../memento-note/docs/brainstorm-documentation.md) | Dev | Architecture brainstorm |
+| [gtm-pricing-strategy.md](../gtm-pricing-strategy.md) | Business | Tarification GTM |
+
+---
+
+*Dernière mise à jour des captures : génération automatique sur instance locale. Pour une doc production, régénérer les PNG après connexion avec un compte de démonstration.*