alex20-create/obsidian-project-sync

Synchronisation de projet Obsidian

Le coffre se décrit lui-même. Où se trouvent les projets, où vont les projets terminés, où le hook laisse ses journaux et quelle note déclare les conventions du coffre : tout cela provient de .claude-vault.json à la racine du coffre, et scan le retourne. Cette compétence ne suppose aucun nom de dossier.

Un coffre n'est pas que des projets, et sa note de conventions indique ce que contient chaque dossier. Gardez cela à l'esprit lorsque vous proposez où mettre quelque chose de nouveau : une décision ou un fait qui concerne plusieurs projets ne va pas dans la note d'un seul projet.

Carte locale d'abord

Recherchez la carte locale de cette compétence avant toute autre chose : une section nommée obsidian-project-sync local map dans les instructions permanentes de l'utilisateur (ses fichiers CLAUDE.md dans Claude Code, lus depuis le disque plutôt qu'à partir de la copie dans le contexte, qui peut être antérieure à une modification ; les instructions du projet ou les préférences de l'utilisateur dans claude.ai). Une section nommée Local map for this install à l'intérieur de ce SKILL.md, ajoutée lorsque la compétence a été empaquetée pour un compte claude.ai, compte aussi ; les instructions permanentes qui disent le contraire l'emportent. Elle contient ce que seule cette installation sait : le chemin du coffre, les conventions propres de l'utilisateur en plus de celles du coffre (notes compagnes que chaque projet porte, styles de callouts), d'autres fichiers qui pointent vers le coffre et doivent changer avec lui. Suivez-la là où elle parle ; elle remplace les valeurs par défaut ici.

Le script et le coffre

Le script est scripts/vault.py, à côté de ce SKILL.md : construisez son chemin à partir du dossier de la compétence elle-même (Claude Code indique le répertoire de base lorsque la compétence est chargée). Chaque exemple ci-dessous l'écrit sous la forme vault.py. Il nécessite Python 3.8 ou ultérieur ; si python n'est pas trouvé, essayez python3, puis py.

Le chemin du coffre provient, dans cet ordre, de la carte locale, de la variable d'environnement OBSIDIAN_VAULT, ou en demandant à l'utilisateur. Transmettez-le avec --vault, avant ou après la sous-commande. Le script n'a intentionnellement pas de valeur par défaut intégrée : sans coffre, il s'arrête et le dit.

Toujours d'abord : regarder avant d'écrire

python vault.py scan --vault "<coffre>"

Sans --project, il retourne l'inventaire du coffre : quels projets existent, dans quelle zone et avec quel status. statuses_in_use liste les valeurs que l'utilisateur utilise déjà ; choisissez-en une et n'inventez pas d'étiquettes.

Ensuite le projet lui-même :

python vault.py scan --vault "<coffre>" --project "<nom du dossier>"

Il retourne le dossier, la note principale, son frontmatter, la liste exacte de ses titres, les autres fichiers du dossier, le journal de session (et quel fichier de journal il a lu, dans session_log_file), et sessions_since_note_changed : les sessions enregistrées plus récentes que la dernière modification de la note sur le disque. Cette dernière liste est le point de départ pour « ce qui n'est pas encore dans la note », pas une preuve : vérifiez-la par rapport à la note avant d'affirmer que quoi que ce soit manque.

--project prend le nom du dossier du projet dans le coffre, comparé sans casse ni accents. Lorsque vous travaillez à partir d'un dépôt de code, le dossier a généralement le nom du dépôt ; sinon, exécutez scan sans --project et faites correspondre par le frontmatter de la note principale (une clé path ou url, si le coffre en utilise une), et demandez quand rien ne correspond.

Un projet dans la zone d'archive est terminé. Ne le recréez pas parmi les projets actifs et ne le mettez pas à jour sans demander.

Deuxièmement : lire les conventions du coffre

scan retourne un bloc config :

"config": {
  "source": ".claude-vault.json",
  "projects": "Projets",
  "archive": "Archive",
  "logs": "Boîte à outils/Claude Sync",
  "conventions": "/chemin/vers/coffre/Meta/Conventions.md"
}

conventions est la note qui fait autorité. Lisez-la avant d'écrire dans une autre : elle déclare le schéma du frontmatter, comment les notes sont écrites dans ce coffre, ce qui peut changer sans demander et ce qui ne le peut pas. Cette compétence n'en transporte délibérément aucune copie : une copie vieillit, et une version antérieure de cette compétence s'est retrouvée à pointer vers un dossier qui n'existait plus.

Si conventions est null, le coffre n'en déclare aucune. Demandez avant d'écrire dans une note.

Le même bloc indique d'où viennent les dossiers. Si source est defaults, le coffre ne s'est pas décrit et vous travaillez sur des hypothèses : dites-le, et proposez d'écrire .claude-vault.json (format dans references/mechanics.md). Si un warning apparaît, la configuration est cassée et doit être corrigée avant de continuer.

Chaque dossier de projet est différent : certains ne contiennent que la note et un canvas, d'autres transportent des notes volantes. Faites confiance à scan, jamais à ce qui était là la dernière fois.

Écrire dans une note

Les notes sont écrites à la main. Il n'y a pas de modèle ni de marqueurs cachés, et aucun n'est ajouté. Le corps d'une section spécifique est remplacé :

python vault.py section --vault "<coffre>" --note "<chemin>" --heading "Déploiement" --content "<fichier>" --dry-run

Le titre est comparé sans emoji et par correspondance partielle, donc Déploiement trouve ## 🚀 Déploiement. S'il n'y a pas de correspondance, le script liste les titres qui existent au lieu d'en inventer un.

--content est un fichier contenant le nouveau markdown. Écrivez-le dans un dossier temporaire (le bloc-notes de la session, ou le dossier temporaire du système), jamais à l'intérieur du coffre ou d'un dépôt de code, et supprimez-le ensuite.

Règles qui comptent vraiment :

• --dry-run d'abord, toujours, et le oui de l'utilisateur avant l'écriture réelle. Montrez à l'utilisateur le diff du dry-run, dites si chaque changement est factuel ou en prose, et attendez. Exécutez la même commande sans --dry-run seulement après qu'il a accepté ; un seul oui couvre les diffs qu'il a vus, rien d'autre.
• --content transporte toute la section, pas seulement ce qui change. replace échange tout le corps sous ce titre. N'envoyez qu'un tableau et la prose en dessous disparaît. Lisez la section actuelle, intégrez-y le changement et envoyez le résultat complet.
• La dernière section de la note est protégée. Les liens de pied de page vivent généralement en dessous, n'appartiennent à aucune section et seraient perdus. Le script s'arrête avec le code de sortie 2 et le dit. Utilisez --mode append pour ajouter sans supprimer, ce qui est presque toujours correct pour un journal continu comme Modifications récentes.
• append respecte les callouts. Lorsqu'une section est un callout délimité (```ad-note, du plugin Admonition), le nouveau texte va à l'intérieur du bloc, avant sa ligne de fermeture ; lorsqu'il s'agit d'un callout natif (> [!note]), les nouvelles lignes sont citées pour rester à l'intérieur. Le pied de page reste en dernier dans les deux cas.
• Imitiez ce qui est là. Langue, voix, prose ou puces, longueur : la note de conventions du coffre le déclare, et la note que vous êtes sur le point de toucher le confirme. Lisez-la avant de rédiger.
• Vérifiez avant d'affirmer. Un nombre, une version ou un statut écrit dans une note doit provenir de quelque chose que vous avez lu ou exécuté dans cette session. S'il ne peut pas être vérifié maintenant, omettez-le ou dites qu'il n'est pas vérifié.

Ajouter une nouvelle section nécessite de dire où elle va : --heading "Test" --after "Pièges". Demandez d'abord : une nouvelle section change la structure d'un document que l'utilisateur a écrit.

Ce que vous pouvez changer sans demander

Le coffre le déclare, dans sa note de conventions : la partie qui dit ce qui est factuel et vérifiable (et donc corrigé sans demander) et ce qui est prose, qui n'est pas touchée sans permission.

Jusqu'à ce que vous l'ayez lue, traitez tout comme de la prose et demandez.

Lorsque de nouvelles informations ne correspondent à aucune section existante, proposez les deux options et laissez l'utilisateur choisir : étendre une section, ou une note séparée liée depuis la note principale. Ne décidez pas vous-même.

Frontmatter

Le schéma appartient à chaque coffre et sa note de conventions le déclare. scan retourne le vrai frontmatter de chaque note, ce qui est l'autre moyen de le voir.

python vault.py frontmatter --vault "<coffre>" --note "<chemin>" --set updated=2026-09-13 --dry-run

Clés scalaires uniquement. Le script refuse délibérément les listes en bloc : changer les sujets d'une note est la décision de l'auteur. section --touch-updated définit déjà la date, donc cela est rarement nécessaire seul.

Un champ appartenant à un plugin (un autocollant, une icône) n'est jamais touché.

Canvas

Les fichiers .canvas sont du JSON avec nodes et edges (JSON Canvas 1.0). La disposition a été faite à la main, avec des groupes et des connexions délibérés.

python vault.py canvas --vault "<coffre>" --file "<chemin>.canvas" --report

Il donne les nœuds, les arêtes, les noms de groupes, quelles notes sont liées et si l'une d'elles pointe vers un fichier qui n'existe plus.

Et state_outside_its_group, le champ qui nécessite vraiment une surveillance. Un canvas qui groupe les notes par leur state stocke ce fait deux fois : dans le frontmatter et dans la position et la couleur du nœud. Changez le state, laissez la carte où elle était, et le canvas ne se casse pas ; il pointe toujours vers un fichier qui existe et affiche toujours l'ancienne couleur. Il commence à mentir sans rien pour avertir personne.

Ainsi, chaque fois que vous changez un state, vérifiez si ce projet ou dossier a un canvas qui groupe par état, et exécutez le rapport. L'inverse est également vrai : après avoir créé une note, vérifiez qu'elle a une carte. Une note qui n'est pas sur le tableau n'existe pas pour celui qui lit le tableau.

Le corriger signifie déplacer le nœud et le recolorer, ce qui est une modification manuelle : le script rapporte, il ne réorganise pas. Dites-le et proposez le changement.

python vault.py canvas --file "<chemin>.canvas" --add-file "Chemin/Relatif/Note.md" --color 6 --dry-run

Les nouveaux nœuds atterrissent dans un espace en dessous de tout ce qui existe : rien de déjà présent ne bouge. Les placer à l'intérieur d'un groupe est le travail manuel de l'utilisateur, et à juste titre. Exécutez-le à nouveau sans --dry-run une fois que l'utilisateur a accepté.

Si le rapport montre des liens cassés, dites-le et arrêtez-vous. Ne supprimez pas de nœuds.

Le journal de session

Un hook SessionEnd enregistre les données brutes de chaque session Claude Code dans le dossier de journaux que le coffre déclare (config.logs), un JSON par dépôt : date, branche, nouveaux commits depuis la dernière fois, fichiers touchés et si quelque chose a été laissé non commité. Il n'écrit dans aucune note.

C'est la matière première. Lorsque l'utilisateur demande une mise à jour, scan --project l'apporte déjà lu, dans session_log et sessions_since_note_changed. Vérifiez ces commits par rapport à ce que dit la note et proposez quelles sections sont devenues obsolètes.

Si le hook n'est pas encore installé, lisez references/hook-install.md.

Notes d'une conversation claude.ai

Les projets claude.ai ne sont pas sur le disque, donc il n'y a pas de script là-bas. Écrivez le markdown complet dans un bloc de code, avec un frontmatter qui suit le schéma du coffre de l'utilisateur (demandez-le, ou demandez une note existante à copier, si vous ne le connaissez pas), et dites où l'enregistrer. Si le projet a déjà une note, dites dans quelle section le coller plutôt que de créer un fichier volant.

En cas d'échec

• python n'est pas reconnu : essayez python3, puis py. Si aucun ne fonctionne, il n'y a pas de Python ; dites-le et proposez de faire la modification à la main avec les outils de fichiers, ce qui est plus lent et plus risqué.
• « Aucun coffre donné » : la carte locale n'a pas de chemin de coffre et OBSIDIAN_VAULT n'est pas défini. Demandez le chemin à l'utilisateur et proposez de l'ajouter à la carte locale.
• Le script s'arrête avec le code de sortie 2 : c'est la protection de la dernière section qui fait son travail. Passez à --mode append.
• Le diff montre plus de suppressions que prévu : n'écrivez pas. Presque toujours --content était incomplet.
• Le dossier du projet n'existe pas : demandez. Ne créez pas de nouveaux dossiers dans la zone des projets par vous-même.

Références

• references/hook-install.md : installation du hook de journalisation de session, sur Windows, macOS et Linux.
• references/mechanics.md : comment le script fonctionne et ce qu'il garantit : le fichier de configuration, comment un titre est trouvé, les protections, le format du journal.

Les conventions d'écriture ne sont pas ici. Elles vivent dans le coffre, dans la note que scan retourne dans config.conventions.