# 🚀 Guide de prise en main

Ce guide vous fait passer d'une installation fraîche à une utilisation courante
d'ObsiGate : première connexion, découverte de l'interface, navigation dans vos
vaults Obsidian et raccourcis essentiels.

> **Public :** tous les utilisateurs · **Durée de lecture :** ~10 min
> **Voir aussi :** [Déploiement Docker](./DEPLOIEMENT_DOCKER.md) ·
> [Recherche, PDF, Excel & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) ·
> [API REST](./API_REST.md)

---

## 1. Qu'est-ce qu'ObsiGate ?

ObsiGate est une **porte d'entrée web ultra-légère** vers vos vaults Obsidian.
Il indexe vos notes en mémoire, les rend accessibles depuis n'importe quel
navigateur (ordinateur, tablette, téléphone) et ajoute une couche moderne :
recherche avancée, lecture Markdown, liens `[[wikilinks]]`, images, PDF,
Excalidraw, Mermaid, assistant IA, collaboration temps réel.

Points clés :

- **Aucune modification de vos vaults** : les volumes sont montés en lecture seule (`:ro`) par défaut.
- **Pas de base de données** : tout l'état tient dans des fichiers JSON sous `data/`.
- **Temps réel** : un watcher surveille le système de fichiers et met l'index à jour à chaud.
- **Multi-vault** : plusieurs vaults peuvent être affichés et recherchés simultanément.

---

## 2. Prérequis

| Composant | Version | Remarque |
|---|---|---|
| Docker | ≥ 20.10 | ou Node/`uv` pour un lancement manuel |
| docker-compose | ≥ 2.0 | inclus avec Docker Desktop |
| Navigateur | récent | Chrome, Edge, Firefox, Safari |

Vous aurez aussi besoin du **chemin absolu** de chaque vault Obsidian sur la
machine qui héberge Docker.

---

## 3. Lancer ObsiGate en 3 étapes

> La procédure complète (reverse proxy, HTTPS, mises à jour) est détaillée dans le
> [Guide de déploiement Docker](./DEPLOIEMENT_DOCKER.md).

### 3.1 Cloner le dépôt

```bash
git clone https://git.dracodev.net/Projets/ObsiGate.git
cd ObsiGate
```

### 3.2 Déclarer vos vaults

Éditez `docker-compose.yml` pour monter vos dossiers (chemins absolus, lecture seule) :

```yaml
volumes:
  - /home/user/Documents/Obsidian-Recettes:/vaults/Recettes:ro
  - /home/user/Documents/Obsidian-IT:/vaults/IT:ro
  - ./data:/app/data   # persistance auth/config
environment:
  - VAULT_1_NAME=Recettes
  - VAULT_1_PATH=/vaults/Recettes
  - VAULT_2_NAME=IT
  - VAULT_2_PATH=/vaults/IT
```

Créez le fichier de secrets à partir du modèle :

```bash
cp .env.example .env
# Éditez .env (mot de passe admin, options d'auth…)
```

### 3.3 Construire et démarrer

```bash
chmod +x build.sh   # une seule fois
./build.sh
```

`build.sh` vérifie Docker, valide les volumes, construit l'image et démarre le
conteneur. Ouvrez ensuite **http://localhost:2020**.

> Options utiles : `./build.sh --help`, `./build.sh --cache` (rebuild rapide),
> `./build.sh --build-only` (construire sans démarrer).

---

## 4. Premier accès

### 4.1 Si l'authentification est désactivée (défaut)

Vous arrivez directement sur l'interface. Toutes les fonctionnalités sont
accessibles sans compte — **à réserver à un usage sur réseau de confiance**.

### 4.2 Si l'authentification est activée

L'écran de connexion s'affiche. Au **tout premier démarrage**, ObsiGate crée un
compte admin et affiche le mot de passe **une seule fois dans les logs** :

```bash
docker compose logs obsigate | grep -A4 "FIRST"
```

Changez ce mot de passe dès la première connexion (menu → profil →
*Changer le mot de passe*). La gestion complète des comptes, du MFA et des
permissions est décrite dans le
[Guide Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md).

---

## 5. Découvrir l'interface

L'interface se compose de trois zones principales.

### 5.1 L'en-tête (header)

| Élément | Rôle |
|---|---|
| 🔍 **Barre de recherche globale** | Recherche dans toutes les vaults autorisées |
| Filtre | Restreint la recherche (type, tag, vault…) |
| Sélecteur de vault | Bascule l'arborescence sur une vault ou « Toutes les vaults » |
| Utilisateur | Nom du compte connecté (si auth activée) |
| Version | Version courante d'ObsiGate |
| ⚙️ **Options** | Configuration, thème, guide d'utilisation, administration |

### 5.2 La barre latérale (sidebar)

Elle regroupe les vues principales via des icônes :

- **Arborescence** — parcourt les dossiers et fichiers de la vault sélectionnée.
- **Graphe** — vue force-directed des liens entre notes.
- **Récents** — derniers fichiers ouverts.
- **Signets** — vos fichiers et recherches enregistrés.
- **Partagés** — liens de partage public que vous avez créés.

Un champ **« Filtrer fichiers… »** restreint l'arborescence en temps réel, et le
bouton **Aa** ajuste l'affichage des libellés.

En bas de la sidebar (si l'authentification est activée), la **section compte**
affiche votre avatar (ou vos initiales), votre nom et votre rôle ; un clic ouvre
le profil. La photo se choisit dans **Configurations → Profil** (*Choisir une
image* : PNG, JPG ou WEBP — recadrée en carré 256 px, affichée dans le cercle de
la sidebar) ; le bouton *Se déconnecter* est juste à côté.

### 5.3 La zone de contenu

Elle affiche l'onglet actif : tableau de bord **Statistiques**, **Bookmarks**,
**Récents**, **Partagés**, ou le document ouvert. Les documents s'ouvrent dans
des **onglets** (avec possibilité de vue multi-panneaux / split view).

---

## 6. Navigation et lecture

1. **Déployez une vault** dans la sidebar (clic sur son nom).
2. **Cliquez sur un dossier** pour l'ouvrir, sur un **fichier** pour l'afficher.
3. Le **breadcrumb** en haut du document permet de remonter rapidement.
4. Les **wikilinks** `[[note]]` sont cliquables ; les images et diagrammes
   s'affichent automatiquement.
5. Utilisez **Ctrl + clic** sur un lien pour l'ouvrir en aperçu rapide selon le
   contexte, ou ouvrir le graphe centré sur un nœud.

### Créer et modifier

- **Bouton « Editer »** : ouvre le document dans l'éditeur Markdown (CodeMirror).
- **Bouton « Forge »** (éditeur avancé) : ouvre la version enrichie avec
  assistant IA intégré. Voir [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md).
- **Nouveau fichier / dossier** : depuis les actions de la sidebar ou la palette
  de commandes.
- **Sauvegarde** : `Ctrl + S` (et auto-sauvegarde dans l'éditeur IA).

> Selon le mode, la lecture et l'édition se remplacent : `Editer` et `Forge`
> prennent la place de la vue lecture ; revenez avec `✓` / `×` ou `Échap`.

### Discuter d'un fichier

- **Bouton « Chat »** (💬, barre d'actions du document) : ouvre un panneau
  latéral avec l'historique de la discussion et la saisie d'un message.
- Les nouveaux messages s'affichent en direct ; si le panneau est fermé, une
  notification annonce l'envoi. L'historique est conservé par fichier.
- Le panneau **suit le document** : changer de fichier re-cible la discussion.

### Chat général

- Onglet **💬 Chat** (dernier de la sidebar, sous les onglets) : conversation
  centrale, valable pour toute l'application, avec **pastille rouge** quand
  de nouveaux messages arrivent.
- **📎** attache une image ou une vidéo (25 MB max) ; les URL sont cliquables.
- La **barre de filtre** sert à chercher dans le chat (texte ou auteur) quand
  cet onglet est actif.
- **🗑** (survol d'un message) : supprime votre message — un administrateur
  peut supprimer celui de n'importe qui. Confirmation demandée, le retrait
  est immédiat pour tout le monde.
- **Messages privés** : la rangée de pastilles au-dessus du fil propose
  **Général** puis chaque utilisateur ; choisissez un destinataire pour une
  conversation à deux, avec son propre compteur de non-lus.
- **Link preview** : coller une URL suffit — titre, description, image et
  site s'affichent en carte cliquable sous le message (si le site répond).

---

## 7. Rechercher

La recherche est un point fort d'ObsiGate : index inversé TF-IDF, stemming
français, normalisation des accents, facettes et pagination. La syntaxe complète
(`tag:`, `#`, `vault:`, `title:`, `path:`, `ext:`, phrases exactes) est décrite
dans le [Guide Recherche, PDF, Excel & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md).

Démarrage rapide :

- Tapez dans la barre de recherche, `Ctrl + K` pour y revenir.
- `/` focalise la recherche hors champ de saisie.
- `/` + `↑`/`↓` navigue dans les suggestions.

---

## 8. Apparence et confort

- **Thème clair/sombre** : bascule persistée en `localStorage` ; le desktop suit
  aussi le thème du système.
- **Thèmes** : clair, sombre, contraste élevé, sépia — import/export possible.
- **Responsive** : l'interface s'adapte au mobile (éditeur tactile, barre
  d'outils flottante).
- **PWA** : installable comme application native, mode hors-ligne partiel.

Voir [PWA & mode hors-ligne](./PWA_HORS_LIGNE.md).

---

## 9. Raccourcis clavier essentiels

| Action | Raccourci |
|---|---|
| Palette de commandes | `Ctrl + Shift + Space` |
| Palette de fichiers (navigation rapide) | `Ctrl + Alt + Space` |
| Focus barre de recherche | `Ctrl + K` |
| Recherche rapide (hors champ texte) | `/` |
| Sauvegarder le fichier ouvert | `Ctrl + S` |
| Rechercher dans le document | `Ctrl + F` |
| Completion IA inline (éditeur) | `Ctrl + J` |
| Insertion rapide (éditeur Forge) | `Alt + I` |
| Fermer l'éditeur / modale | `Échap` |
| Aide de l'éditeur Forge | `F1` |
| Naviguer dans les suggestions | `↑` / `↓` |
| Lancer la recherche / valider | `Entrée` |

> Le panneau **Raccourcis & Astuces** du tableau de bord Statistiques récapitule
> ces raccourcis directement dans l'application.

---

## 10. Et ensuite ?

| Objectif | Guide |
|---|---|
| Mieux chercher, lire PDF/Excel et Excalidraw | [Recherche, PDF, Excel & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) |
| Utiliser l'IA intégrée | [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) |
| Éditer à plusieurs | [Édition & collaboration](./COLLABORATION.md) |
| Sécuriser l'accès | [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) |
| Automatiser via API/MCP | [API REST](./API_REST.md) · [MCP](./MCP.md) |
| Installer l'application native | [Desktop (Tauri)](./DESKTOP.md) |