Knowledge Base — règles de maintenance

À lire dans toute nouvelle session Claude / contributeur sur ce projet. Ce document est la source de vérité unique sur la structure, les règles d'écriture et les rythmes de mise à jour des deux KB principales : news/ (journal géo-politico-économique) et assets/ (mdbooks par instrument).

1. Structure du repo KB (edge-pages)

Repo dédié, public, séparé du repo de code (edge-research privé).

edge-pages/
├── README.md               ← landing page repo (sans contenu KB)
├── book.toml               ← config mdbook
├── .github/workflows/publish.yml  ← CI mdbook → Pages
├── src/
│   ├── SUMMARY.md          ← table des matières mdbook
│   ├── README.md           ← landing page du book
│   ├── MAINTENANCE.md      ← ce fichier (règles)
│   ├── news/               ← gazette : 1 fichier par fait/article
│   │   ├── README.md
│   │   ├── 2026-05-08-fomc-pause.md
│   │   └── ...
│   └── assets/             ← 1 dossier par asset whitelist
│       ├── README.md
│       ├── GOLD/
│       │   ├── identity.md   (carte d'identité)
│       │   ├── mood.md       (humeur — actuelle + historique 4 sem)
│       │   └── timeline.md   (références chronologiques aux articles news)
│       ├── OIL/
│       ├── SPX500/
│       ├── DJ30/
│       ├── NSDQ100/
│       ├── FRA40/
│       ├── GER40/
│       └── UK100/

2. Règles d'écriture — News

Principe : un fait = un article, plusieurs sources possibles

Chaque article rapporte un fait observé (ex: "FOMC pause taux", "OPEC+ coupe production", "ECB préside Lagarde dovish") et cite les sources qui l'ont relayé. Pas de doublon : si Reuters et Bloomberg couvrent le même fait, un seul article avec deux références.

Mise en page (style gazette moderne, sobre)

---
title: "Titre concis et factuel"
date: 2026-05-08T16:30:00Z
slug: 2026-05-08-fomc-pause
category: macro|geopol|earnings|crypto|commodities
impact_assets: [SPX500, NSDQ100, GOLD]
sentiment: neutral|bullish|bearish
sources:
  - { name: Reuters, url: https://reuters.com/..., published: 2026-05-08T16:25Z }
  - { name: Bloomberg, url: https://bloomberg.com/..., published: 2026-05-08T16:28Z }
---

# Titre concis et factuel

> **TL;DR** — une phrase qui résume le fait et son impact.

## Le fait

Description neutre et factuelle, max 4 paragraphes. Pas d'opinion, pas
d'interprétation spéculative ; uniquement ce qu'on sait de source(s).

## Lecture pour le trading

Comment ce fait a été (ou pourrait être) interprété par les marchés.
Référencer les **assets impactés** avec leur slug (`[[GOLD]]`, `[[SPX500]]`).
Cette section est indispensable — sinon l'article n'a pas sa place dans cette KB.

## Liens vers assets

- [[GOLD]] — réaction immédiate −0.4 % en 5 min, voir [GOLD timeline](../assets/GOLD/timeline.md)
- [[SPX500]] — rally +0.3 % sur 30 min

## Diagramme (optionnel mermaid)

\`\`\`mermaid
flowchart LR
    A[FOMC pause] -->|surprise dovish| B[USD weakening]
    B --> C[GOLD +0.4%]
    B --> D[SPX500 +0.3%]
    A -.->|expected by 60% bps| E[Pricing déjà partiel]
\`\`\`

## Sources

(générées automatiquement depuis le frontmatter `sources` ; format clair)

Quand créer un article news

  • Importance ≥ 0.5 dans le scoring news.py ET impact identifiable sur ≥ 1 asset whitelist.
  • Pas pour les flux de routine (PMI mineurs, déclarations sans surprise).
  • Quand un fait majeur arrive hors news flow (Twitter, breaking) : ajouter manuellement.

Maintenance

  • Ne jamais éditer un article publié pour reformuler le fait ; si le fait évolue, créer un follow-up article (chaîne prev: <slug> dans frontmatter).
  • Ne jamais supprimer un article ; en cas d'erreur grave, ajouter correction: dans frontmatter et un encadré ⚠ en haut.
  • Vérifier les sources restent accessibles ; si un lien meurt, archiver via archive.org et ajouter à sources.

3. Règles d'écriture — Assets

Structure d'un mdbook asset (3 fichiers)

identity.md — carte d'identité

---
symbol: GOLD
etoro_id: 18
name: Gold (Non Expiry CFD)
type: commodity
session: 24h continuous (eToro)
typical_volatility_1m: 0.05% (calm) - 0.15% (event)
costs_round_trip_pct: 0.11
trading_hours_utc: 24h
liquidity: high
correlations:
  positive: [USD inverse, real_yields_inverse, VIX]
  negative: [DXY, US10Y_real]
---

# GOLD — Or (CFD eToro non-expiry)

## Description

L'or coté en CFD eToro, prix au gramme … Description objective, sources eToro.

## Drivers principaux (ordre d'impact)

1. **Politique monétaire US** — taux réels, FOMC, dot plot. Impact attendu majeur.
2. **Géopolitique** — guerres, sanctions, tensions. Impact court-terme intense.
3. **Demande physique** — banques centrales, ETF flows. Impact lent.
4. **USD index (DXY)** — inversement corrélé.
5. **VIX / risk-off** — corrélation positive en stress.

## Spécificités CFD eToro

- Pas de spread overnight si position fermée même journée
- Frais nuit : ~0.04 % / nuit ouvré pour position long
- Granularité min lot : 0.01 oz
- Levier max FR (CFD non-FX) : 10× pour retail (on utilise 3-5×)

## Risques structurels

- Gap weekend : possible si event vendredi soir
- Halte trading : très rare mais possible (krach)

mood.md — humeur actuelle + historique

# GOLD — Mood

> Mis à jour : 2026-05-08 16:00 UTC
> Mood actuel : **neutral-bullish**

## Cette semaine (2026-W19)

Mood : neutral-bullish
- Drivers actifs : ECB attentisme, USD soft → légère pression haussière sur or
- Range observé : 2350-2390 (GOLD coté or par oz)
- Volume : moyen, pas de squeeze
- Articles news liés cette semaine :
  - 2026-05-06 — [ECB minutes — no rate cut signal](../../news/2026-05-06-ecb-minutes.md)
  - 2026-05-08 — [FOMC pause](../../news/2026-05-08-fomc-pause.md) (impact +0.3%)

## 4 dernières semaines

| Semaine | Mood | Range | Événement majeur | Note |
|---|---|---|---|---|
| W19 (cette) | neutral-bullish | 2350-2390 | FOMC pause | Pricing in dovish |
| W18 | bearish | 2290-2350 | NFP fort | Real yields up |
| W17 | bullish | 2300-2380 | CPI cool | Réflation pause |
| W16 | neutral | 2310-2360 | Fed jawboning | Range trade |

## Régime VIX implicite

Mood inversement corrélé au DXY. Si VIX > 25 et géopolitique tendue, mood bullish prioritaire.

timeline.md — chronologie articles news qui ont impacté l'asset

# GOLD — Timeline articles impactants

> Mis à jour : 2026-05-08 16:00 UTC

## 2026-05 (mai)

- **2026-05-08 16:25 UTC** — [FOMC pause](../../news/2026-05-08-fomc-pause.md) — réaction +0.4 % en 5 min, retour à 0 en 20 min (déjà pricé partiellement)
- **2026-05-06 12:00 UTC** — [ECB minutes — no cut signal](../../news/2026-05-06-ecb-minutes.md) — réaction +0.2 % puis fade
- **2026-05-05 14:30 UTC** — [NFP +280k](../../news/2026-05-05-nfp.md) — réaction -0.7 % brutal en 10 min, **stop loss touché sur 2 trades long** (lev 3)

## 2026-04 (avril)

(historique condensé, ≥ impact 0.5 %)

Quand mettre à jour mood + timeline

  • mood : automatiquement chaque vendredi à la fermeture US (21:00 UTC) — script scripts/kb_update_mood.py à créer
  • timeline : chaque fois qu'un article news est publié avec l'asset dans impact_assets
  • identity : rare — uniquement si paramètres CFD eToro changent (frais, levier max)

4. Règles de liaison news ↔ assets (bidirectionnelle)

Chaque article news liste ses impact_assets dans le frontmatter. Un script de maintenance (scripts/kb_link.py à créer) :

  1. Lit tous les articles news, extrait impact_assets.
  2. Pour chaque asset référencé, ajoute une ligne dans son timeline.md (si pas déjà présent).
  3. Vérifie cohérence : tout lien dans un asset/timeline doit exister dans news/.

5. Conventions de fichiers

  • Encoding : UTF-8 sans BOM
  • Line endings : LF
  • Slugs : YYYY-MM-DD-kebab-case pour news ; SYMBOL (uppercase) pour assets
  • Mermaid : préférer flowchart LR / flowchart TB ; pas de graph TD (deprecated)
  • Couleurs Mermaid : rester sobre, max 3 couleurs par diagramme, palette : #1f77b4 (bleu), #ff7f0e (orange), #2ca02c (vert), #d62728 (rouge)
  • Pas d'emojis dans les KB sauf cas extrêmement justifié (pictogrammes ⚠️ pour correction, ✅ pour validation factuelle)

6. Pipeline GitHub Pages (privée)

.github/workflows/publish.yml :

  • Trigger : push sur master ou main
  • Build : mdbook build (au root du repo)
  • Deploy : GitHub Pages via actions/deploy-pages@v4
  • URL publique : https://jddellac-hue.github.io/edge-pages/

7. Mémoires Claude vs KB

  • Mémoires Claude (~/.claude/projects/.../memory/*.md) : règles cross-session pour Claude. Ne contient PAS de contenu de KB. Pointe juste vers KB par référence.
  • KB du repo (edge-pages/) : source de vérité versionnée, partagée, accessible publiquement. Toute connaissance utile au-delà d'une session DOIT vivre ici, pas dans les mémoires.
  • En début de session, Claude lit MAINTENANCE.md (ce fichier, dans le repo edge-pages) pour comprendre les règles, et navigue ensuite dans les news+assets pertinents.

8. Commandes utiles

# Build local (depuis racine edge-pages/)
mdbook serve . -p 4000   # http://localhost:4000

# Build statique
mdbook build .           # output → ./book/

# Linting (markdown)
markdownlint src/**/*.md

# Mermaid validation
npx -p @mermaid-js/mermaid-cli mmdc -i input.md -o output.svg

9. Quand créer un asset book

Toujours pour un asset ajouté à WHITELIST dans trade_pipeline.py (repo edge-research). Quand un asset est retiré, archiver son dossier dans src/assets/_archive/, ne pas supprimer.