Momento/AGENTS.md

Agent memory (Momento)

Learned User Preferences

• Préfère les échanges en français, avec des explications détaillées et claires (éviter le jargon flou).
• Interface : tout libellé via i18n dans les 15 fichiers memento-note/locales/*.json (FR et EN comme références de contenu) ; éviter le texte en dur ; traductions contextuelles (sens produit, pas mot à mot — ex. « connecter votre propre fournisseur ») ; libellés FR lisibles (éviter jargon non expliqué : « wiki », « embed », etc.) et aide contextuelle où l'UX l'exige ; lors d'une traduction complète, mettre à jour toutes les locales concernées ; si l'utilisateur demande seulement les clés i18n, ajouter les clés (souvent EN/FR) sans remplir les 15 locales — il traduit souvent avec un autre modèle.
• Base de données : INTERDIT TOTALEMENT de lancer prisma db push --force-reset, prisma migrate reset, DROP TABLE, TRUNCATE, pg_restore avec clean, ou TOUTE commande qui vide/supprime des données — MÊME SI l'utilisateur est d'accord — sans avoir d'abord : (1) dumpé la base avec bash /home/devparsa/dev/Momento/dump-db.sh, (2) vérifié le dump fait au moins 1Mo, (3) obtenu un "OUI" explicite de l'utilisateur. 4 incidents de perte de données documentés (14/05, 15/05 x2, 16/05). NE JAMAIS REFAIRE ÇA.
• Design produit : migration depuis architectural-grid1 (base) et architectural-grid (prototype UI courant) ; consulter le prototype avant toute implémentation UI ; logique liste/carte puis contenu au clic ; parité actions liste/carte (menus « … », déplacer, génération SVG, etc.) ; contraste éditeur clair / sidebar sombre ; retirer thèmes obsolètes ; pas de refresh/revalidation complets inutiles (aligné prototype — mutations optimistes, pas de revalidatePath systématique ni resync depuis initialNotes) ; Memory Echo en section inline dans l'éditeur (pas l'ancienne modale) — similarité sur contenu représentatif (pas de troncature arbitraire type 200/800 car.) ; recherche (sidebar / résultats, ex. flux « ouvrir la note ») et navigation liste des notes (modes affichage, icônes vs initiales…) : suivre SearchModal et les patterns actuels dans architectural-grid, pas une approximation ou un ancien flux ; /insights (insights sémantiques) : suivre InsightsView.tsx + graphe réseau associé dans le prototype (ex. composition type NetworkGraph.tsx) ; distincte de /graph ; ne pas substituer par une UX « géométrique » décorative ou un regroupement par carnet hors spec prototype ; lorsque données clusters en retard ou partiellement périmées, montrer l’état dégradé exploitable plutôt qu’une page vide ; si l'utilisateur hésite entre variantes UX, trancher pour le design prototype plutôt que multiplier les toggles.
• Locale persane : dates en calendrier iranien (conversion), chiffres persans, et vérification RTL/positionnement global ; Memory Echo et recherche sémantique doivent fonctionner en persan (RTL, embeddings — pas de contournement « EN only ») ; attention à ne pas confondre un nom de carnet (ex. « Persan ») avec le libellé de langue.
• Flux Excalidraw / diagrammes générés : accès via notification en plus d'une simple redirection ; priorité à la mise en page et au texte contenu dans les formes ; proposer des modes visuels (ex. coloré vs plus austère) tout en visant un rendu proche du style Excalidraw (polices, look).
• Interdiction d'écrire des tests sauf demande explicite ; en CI, seul npm run test:unit (tests/unit/**) — pas tests/migration/ ; ne jamais générer de code superflu.
• Déploiement : privilégier le chemin rapide (artifact Next.js en CI + Dockerfile.prebuilt) ; CI/CD très robuste (pas d'image Docker obsolète en prod, pas de migrations/schéma DB via le workflow deploy) ; éviter les rebuild Docker complets inutiles (~15 min par itération) ; ne pas pousser un déploiement quand des features clés sont inachevées ; ne pas insister sur le déploiement tant que le produit n'est pas fini ou meilleur.
• Authentification : priorité à l'inscription/connexion via Google OAuth (plutôt qu'un compte email/mot de passe) ; exiger une vraie déconnexion (invalidation session/cookies — pas de reconnexion implicite, y compris en navigation privée).
• Priorité absolue à la qualité UX, même si l'implémentation est complexe (« je m'en fous si c'est complexe ») ; ne jamais affirmer qu'un correctif ou une feature est fait sans vérification réelle (app, prototype architectural-grid, ou test), notamment navigation recherche/liste notes et vue /insights vs fichiers prototype — l'utilisateur sanctionne fermement les fausses déclarations ; en frustration ou pour déléguer, prévoir des prompts / briefs d'implémentation détaillés (autre modèle ou dev), en plus des briefs outil de design.
• Livraison : une user story à la fois, tester et valider avec l'utilisateur avant la suivante ; suivi dans docs/user-stories.md.
• Quand demandé, fournir des briefs pour un outil de design externe plutôt que produire les maquettes UX soi-même.

Learned Workspace Facts

• Application Next.js principalement sous memento-note/.
• Référentiels design du workspace : architectural-grid1/ et architectural-grid/ à la racine du repo Momento.
• i18n : 15 fichiers sous memento-note/locales/ (de, en, es, fr, it, pt, nl, pl, ru, zh, ja, ko, ar, fa, hi) ; logique sous memento-note/lib/i18n/ ; référence en.json (~2218 clés) ; auditer les « non traduits » par flatten EN vs locale (souvent valeurs identiques à l'EN).
• Workflow BMad : stories sous docs/ (ex. 3-4-host-pays-session-logic.md), suivi sprint dans docs/sprint-status.yaml et stories courantes dans docs/user-stories.md ; skills sous .claude/skills/bmad-* ; _bmad-output/planning-artifacts souvent vide — planification de référence dans docs/ ; préférer une user story par feature (pas de stories groupées).
• PostgreSQL Docker (memento-postgres) sur le port 5433 ; Redis Docker (memento-redis) sur le port 6379 (voir règles projet).
• Règles opérationnelles Prisma et sécurité base de données décrites dans CLAUDE.md à la racine du repo.
• Production : dépôt /opt/memento sur 192.168.1.190, conteneur memento-note sur le port 3000, URL publique https://memento-note.com (nginx + Cloudflare ; ancien domaine note.parsanet.org) ; NEXTAUTH_URL aligné sur ce domaine ; email sortant via Resend (SMTP_FROM ex. noreply@memento-note.com, domaine vérifié sur resend.com) ; deploy (deploy.yaml / deploy-prod.sh) sans toucher Postgres (pas de postgresql-client, pas de migrations auto en prod).
• CI/CD Gitea : .gitea/workflows/ci.yaml — CI sur ubuntu-24.04, deploy sur runner docker-host (sur le serveur) ; deploy manuel via .gitea/workflows/deploy.yaml ou bash scripts/deploy-prod.sh.
• Migrations dans l'image prebuilt : docker compose exec memento-note node ./node_modules/prisma/build/index.js migrate deploy (pas npx prisma dans le PATH) ; helper scripts/migrate-docker.sh.
• Vérification deploy : GET /api/build-info (SHA Git) ; comparer 127.0.0.1:3000 et le domaine Cloudflare — purger le cache si versions divergent ; 403 sur /api/manifest côté domaine = souvent Cloudflare, pas l'app.
• Sync mutations notes entre composants : memento-note/lib/note-change-sync.ts (emitNoteChange, événement NOTE_CHANGE_EVENT).
• Roadmap / écart prototype vs prod : Web Clipper — ClipperSimulator.tsx = référence design uniquement (pas de simulateur en prod à la place de l'extension) ; Living Blocks (UniqueID / embeds dans le prototype), Structured Views, Flashcards IA SM-2 (RevisionView.tsx), graphe knowledge (GraphKnowledgeMap.tsx), insights sémantiques (InsightsView.tsx + graphe réseau associé dans le prototype) — /insights ≠ /graph ; prod : extension navigateur memento-note/extension/ v0.2 Side Panel (mode sélection : popup Chrome se ferme au clic page — limitation plateforme) ; host_permissions / origins couvrant l'URL serveur y compris LAN ; URL serveur configurable dans les paramètres extension en dev ; cookies/session alignés avec l'instance cible ; publication Chrome Web Store : icônes 16/48/128, privacy policy, host_permissions prod restreints vs build dev ; network-graph.tsx, /insights, note-document-info-panel.tsx, note-history-modal.tsx, rich-text-editor.tsx.