# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **competitive multiplayer civilization-building tabletop RPG** (JDR - Jeu de Rôle). Multiple players each control their own civilization, guided by a GM (Arthur Ignatus) through choice-based narrative gameplay. The player (Rubanc) controls the "Civilisation de la Confluence" by playing as the Oracle/Arbitre des Esprits - a divine/tuttelary entity guiding the civilization across millennia. All content is in French.

**Game Format:**
- Players make strategic choices that permanently shape their civilization
- Generational time scale: decades or centuries pass between turns
- First contact with foreign civilizations has occurred (Cheveux de Sang discovered at sea)
- Players develop unique technologies and political systems for competitive advantage

## Repository Structure

- **Background/**: Contains all game documentation
  - **Individual interaction files** (e.g., `2025-09-08-la-grande-fresque.md`): Each GM post/turn as separate dated file (PRIMARY SOURCE)
  - `Archive/Background.md`: Complete game transcript (archived, 136KB, 1077+ lines) - use individual files instead
- **Root directory - Current work:**
  - `nextUpdate.md`: **Current draft response** to latest GM post with strategic analysis
  - `PLAN_MISE_A_JOUR_DOCUMENTS.md`: Planning for updates to strategy documents
- **Root directory - Strategy documents:**
  - `OBJECTIFS STRATÉGIQUES - CIVILISATION DE LA CONFLUENCE.md`: Planned objectives by timeframe (court/moyen/long terme)
  - `Le Système Politique  L'Oligarchie Consociationnelle des Cinq Castes.md`: Five-caste oligarchy design
  - `SYSTEME_MILITAIRE.md`: Military doctrine, defensive tactics, Faucons Chasseurs organization
  - `DIAGNOSTIC DES DYSFONCTIONNEMENTS SYSTÉMIQUES.md`: Analysis of systemic problems

**Key Distinction:** `Background/` contains game history as individual turn files (primary source). Root contains current work (`nextUpdate.md`) and strategic planning documents.

## Current Civilization State

### Social Groups (Evolving into Five-Caste System)

The civilization is transitioning from tribal society toward a planned five-caste oligarchy:

**Current Groups:**
- **Ciels-clairs** (Sky-blessed): Born under clear skies, eyes with aurora colors (red/orange/violet), spiritual/leadership elite
  - **Voix de l'Aurore** (Voices of Dawn): Led by Ailes-Grises shamans, defend ancient laws and sacred rituals
  - **Faucons Chasseurs** (Hunter Falcons): Emerging proto-Caste du Feu with triple role: military (defense, command), judicial (justice local), religious (ritual participation). Elite permanent force (2-5 per village) based in Halls des Serments. Theocratic vassalage via annual pilgrimage to La Confluence.
- **Sans-ciels** (Cloudborn): Born under cloudy skies, divided into specialized groups
  - **Enfants du Courant** (Children of the Current): Live in villages on stilts over rivers, control fishing and aquatic resources
  - **Enfants des Échos** (Children of the Echoes): Live in underground Antres (colonies), physically adapted to caves (pale, elongated limbs, often blind), master stoneworkers and miners. Control monopoly on living clay production. Culturally isolated from surface dwellers ("don't like those from the surface"). Will eventually merge with surface artisans to form future caste Terre.
- **Gardiens de la Confluence** / **Passes-bien**: Mixed caste of merchants and mediators who transport goods and messages across the valley

**Planned Five-Caste System (from strategy documents):**
1. **Air**: Spiritual leadership, legislative monopoly (Conseil des Sages)
2. **Feu**: Military and security
3. **Eau**: Water-based resources and naval power
4. **Terre**: Innovation, crafting, construction, mining
5. **Éther**: Commerce, mediation, economic arbitration (only truly mixed caste)

### Key Political Institutions

- **Cercle des Sages** (Circle of Sages): Spiritual council that sets major orientations
- **Tribunal des Mœurs** (Tribunal of Morals): Handles moral conflicts and serious crimes
  - **Proclamateurs**: Judges appointed by the Arbitre for grave matters
- **Assemblée des Chefs** (Assembly of Chiefs): Three chiefs (Cercle des Sages, Tribunal des Mœurs, Maison des Découvertes) who implement decisions
- **Maison des Découvertes** (House of Discoveries): Innovation and experimentation institution located at La Confluence (surface), organized with four climatic zones for working with living clay and multi-material experimentation. Led by the most creative artisan. Recruits from all groups, not exclusively Enfants des Échos. Will eventually merge with artisan groups to form future caste Terre.
- **Hall des Serments** (Hall of Oaths): First proto-governmental structure established in the fortified coastal village at the river mouth. Functions as fortress, council, and sanctuary. Architecture: thick stone/living clay walls with watchtower on stilts at summit. Contains armory, reserves, Council Hall, Autel des Pionniers. Watchtower staffed by Regards-Libres and sacred rhombs for communication.
  - **Conseil du Village** (Village Council): Four permanent guardians who govern the coastal settlement:
    1. **1 Faucon Chasseur vétéran + garrison**: Defense and justice
    2. **1 Aile-Grise**: Rituals, spiritual guidance, teaching Glyphes du Gouffre
    3. **1 Passe-bien**: Commerce and trade network
    4. **1 représentant des pêcheurs**: Voice of the fishing community who face the unknown (sea) daily
  - **Annual pilgrimage**: All four council members must return to La Confluence yearly to report to Cercle des Sages, renew oaths via Rituel du Regard Partagé
  - **Compensation**: Council members receive housing in Hall plus food from communal reserves for themselves and families
  - **Philosophy**: Charges to be merited, not hereditary fiefs. First step toward mature oligarchy where each vital function is represented. Model for future Halls "where our people settle."
- **Arbitre des Esprits** (Arbiter of Spirits): The player character - supreme spiritual mediator with reserve powers, intervenes in crises

### Unique Technologies and Cultural Elements

- **Argile vivante** (Living clay): Clay that hardens almost instantly when exposed to air, critical construction material
- **Glyphes du Gouffre** (Glyphs of the Abyss): Writing system developed at Gouffre Humide, based on modular clay blocks. Two physical formats:
  - **Colliers de glyphes** (Glyph necklaces): Small standardized clay blocks pierced at center, strung on cord with knots at ends. Used for everyday messages, inventories, reports. Reusable - blocks can be unstringed and repurposed. Messengers carry them as necklaces during travel. Produced at Gouffre Humide, distributed by Passes-bien.
  - **Tablettes d'argile** (Clay tablets): Glyphs pressed into living clay before hardening. Permanent records for laws, chronicles, sacred texts. Cannot be altered once hardened.
  - Philosophy: Sacred is the work of composition, not the possession of glyphs. Freedom of local invention encouraged, but Glyphes du Gouffre serves as pragmatic standard for communicating with La Confluence and advancement in castes.
- **Regards-Libres**: Domesticated grey cranes, intelligent scouts used for hunting, fishing, and exploration
- **Ailes-Grises** (Grey-Wings): Shamans who train Regards-Libres, guide souls of the dying
- **Rhombes sacrés**: Sacred stone instruments that produce resonant sounds, used for rituals and long-distance communication
- **Artefacts multi-générationnels**: Objects that are modified by each generation, accumulating history and spiritual power
  - **Grande Fresque des Premiers Ancêtres**: Discovered to be ultimate multi-generational artifact - multilayered fresco showing temporal stratification where each generation painted over previous ones
- **Rituel du Regard Partagé**: Ritual where eye contact (especially with aurora-colored eyes) seals agreements
- **Les Larmes du Ciel**: Traditional dish made with "Morsure-des-Ancêtres" (wild ginger), fish, game, and herbs
- **Cercles de Vigile**: Sacred fires maintained on mountain promontories, connected by Porteurs de Flamme messengers
- **Antres des Échos**: Underground colonies with elaborate carved chambers, workshops, and ritual spaces
  - **Gouffre Humide**: Most mature Antre, now contains the ruins of the Premiers Ancêtres and serves as major pilgrimage and research site
  - Multi-generational carving projects where elderly artisans literally become part of the structure upon death (refuse removal, become part of the Antre - matter of pride)
- **Lois du Sang et de la Bête**: Justice system involving investigation by Faucons Chasseurs, then trial by combat in arena if guilty

### Major Recent Discovery

**Ruines des Premiers Ancêtres** (Ruins of the First Ancestors) discovered beneath Gouffre Humide:
- Ancient underground civilization with advanced techniques (superior pigments beyond ochre/black palette, translucent artifacts that pass light, sophisticated carving in extremely hard rock)
- Hundreds of aligned skeletons (no young, no violence, strange bone appearance suggesting disease or degeneration)
- **Grande Fresque**: Massive multilayered fresco depicting cosmology, sun worship (sun with observing eye), mysterious giants, unknown animals, and paradisiacal/luxuriant land
- Civilization apparently died out from unknown causes (toxic miasmas in lower levels causing sleep then death, no signs of violence)
- Ruins partially inaccessible due to flooding (water inflow exceeds drainage capacity), toxic gases, cave-ins (attempts to clear debris caused secondary collapses), and impenetrable rock
- **Discovery timeline**: Initial discovery during rescue operation (19/08/2025) → became pilgrimage site → multicouche fresco discovery several generations later (08/09/2025)
- Now mandatory pilgrimage site for those wanting to "porter un regard libre" (carry a free gaze)
- Source of theological study, multi-generational fresco interpretation, and deep civilizational anxiety about suffering similar fate
- Phrase: "promis à pareil destin" (promised to similar fate) expresses existential fear

### Recent Historical Events

**Discovery and Exploration of the Ruins (Current Era):**
- Rescue operation revealed ancient ruins with advanced frescoes and architecture
- Initial exploration resulted in multiple casualties from toxic miasmas (explorers fell asleep, then died)
- Subsequent exploration attempts over several generations all failed:
  - Miasmas: Caused majority of deaths, no solution found for air purification
  - Debris clearing: Triggered secondary cave-ins that Enfants des Échos cannot predict or prevent
  - Tunneling attempts: Rock surrounding ruins too hard for current tools (likely why this rock was chosen by Premiers Ancêtres)
  - Drainage attempts: Water inflow exceeds pumping capacity - flooding zones remain inaccessible
- Key quote from exploration failure: "Un échec mordant pour les tiens qui cherchaient à satisfaire tes exigences. Et aussi pour toi, car tes ordres ont directement causé la perte de ceux qui te faisaient confiance."
- Player's response: "Ces galeries ne seront pas notre tombeau, mais le berceau de notre grandeur future. Ce que cette civilisation n'a pu achever, nous le terminerons."

**Evolution Over Generations:**
- Gouffre Humide transforms into major pilgrimage and study site
- Concept of "Premiers Ancêtres" (First Ancestors) emerges as distinct from recent ancestors
- Multi-generational fresco interpretation tradition develops: Ailes-Grises relay in shifts (staying too long underground "suffocates"), memorizing verses, discarding less relevant ones, adding new interpretations like "a debate extending through time"
- Grande Fresque becomes mandatory pilgrimage for anyone wanting to "porter un regard libre" (carry a free gaze)
- Fresco influences all iconography of the civilization - references to it appear throughout art
- Civilizational anxiety develops: fear of suffering same mysterious fate as Premiers Ancêtres
- Accidental discovery of multilayered fresco structure when clumsy aspirant's moist hand damages surface, revealing hidden images underneath

**Current State and Decisions:**
- Gouffre Humide established as multi-caste research campus (not monopolized by any single group)
- Three types of study groups: spiritual (Ailes-Grises), technical (Maison des Découvertes + Enfants des Échos), philosophical (trans-caste)
- Maison des Découvertes tasked with long-term R&D mission: master four technical challenges (ventilation/air purification, hydraulic drainage, advanced tools for hard rock, understanding structural equilibrium)
- New tradition: Autels des Pionniers (Pioneers' Altars) - small roadside shrines in living clay commemorating those who died pursuing knowledge; souls that couldn't reach sky become "guardiens des passages" (guardians of passages)
- Fresco multicouche approach: "Fenêtres temporelles" (temporal windows) - strategic test sections revealing all layers simultaneously, with exhaustive documentation before/after, allowing study without destroying entire work

**Key Challenges:**
- Balancing spiritual reverence (ancestor worship culture) with scientific progress
- Managing access to ruins without allowing caste monopolization
- Addressing technological gaps preventing full exploration
- Understanding cause of Premiers Ancêtres' extinction to avoid same fate

### First Contact with Foreign Civilization

**Discovery of the Cheveux de Sang (28/10/2025):**
- Expansion into lowlands beyond mountain valley revealed vast saltwater sea (impure/undrinkable water)
- Fishermen reported sighting strange floating creature with red-haired humans ("Cheveux de Sang" - Hair of Blood) signaling from its back before disappearing
- **Concept of "l'Autre"** (the Other) introduced: those who share neither ancestors, language, nor known intentions
- Philosophical connection to Premiers Ancêtres' warning: ignorance of the unknown can destroy civilization

**Strategic Response:**
- **Capture strategy adopted**: Observation first (Faucons Chasseurs with Regards-Libres from heights), then opportunistic capture of isolated individuals
- **Objective**: Learn their language, origins, numbers, and intentions through interrogation at Gouffre Humide by Ailes-Grises
- **Command structure**: Faucons Chasseurs act under direct orders from La Confluence
- **Philosophy**: "We must understand the Other in silence, as our cranes hunt in silence"
- **Decision deferred**: Only after gaining knowledge will the civilization decide whether to trade with or repel the Cheveux de Sang
- **Risk accepted**: If capture provokes anger, "we will know what the Other carries in their heart"

## Working with This Repository

### Game Interaction Workflow

**IMPORTANT - Where to check for current game state:**

1. **Latest GM post**: Check `Background/YYYY-MM-DD-*.md` files (sorted by date, most recent = latest turn)
2. **Current draft response**: Check `nextUpdate.md` at project root
3. **Always use individual dated files** - they are the primary source and easier to navigate

**Workflow:**
1. **GM posts new turn** on Discord with choices/narrative
2. **Turn archived** as `Background/YYYY-MM-DD-descriptive-name.md` (e.g., `2025-09-08-la-grande-fresque.md`)
3. **Player drafts response** in `nextUpdate.md` at project root:
   - Context summary of GM's post
   - Strategic analysis of each choice
   - Recommended decisions with justifications
   - Long-term alignment with strategic objectives
4. **Once finalized**, response posted to Discord
5. **Player response appended** to the same `Background/YYYY-MM-DD-*.md` file
6. **Cycle repeats** with new dated file in `Background/` and new `nextUpdate.md`

**To find if player has responded:**
- Check if `nextUpdate.md` exists and contains draft
- OR check if latest `Background/YYYY-MM-DD-*.md` file has player response at the end

### Archived Game Transcript

`Background/Archive/Background.md` is the archived complete game transcript (136KB, 1077+ lines). It contains all turns concatenated together in Discord conversation format.

**IMPORTANT:** This file is archived and no longer updated. Use the individual dated files in `Background/` instead.

**If you need to search the archived transcript:**
- File is too large to read all at once (exceeds token limits)
- Use `offset` and `limit` parameters with Read tool to read sections
- Use Grep to search for specific concepts, choices, or time periods
- For recent turns, **always prefer reading the individual `Background/YYYY-MM-DD-*.md` files** - they are smaller, more focused, and easier to navigate

### Style d'écriture des réponses

**TODO:** Adapter le style des réponses pour mieux correspondre aux attentes d'Arthur. Détails à préciser.

### Language

All documentation is in French. Maintain French for any worldbuilding content additions or modifications.

### ConfluentTranslator API

**IMPORTANT**: When translating French ↔ Confluent or verifying vocabulary, use the live translation API at `https://confluent.etheryale.com`. Claude Code has API access (key in session memory). See `API_CONFLUENT.md` for full documentation. Prefer Ancien Confluent variant for game content.

### Strategic Planning Documents

The three strategy documents represent the player's planning for long-term civilization development:

- **OBJECTIFS STRATÉGIQUES**: Three-tier roadmap (court/moyen/long terme) covering institutional consolidation, caste development, technological advancement, and expansion
- **Le Système Politique**: Detailed design for the mature five-caste oligarchy with checks and balances, including legislative monopoly (Air), executive power (Directoire), judiciary (Proclamateurs), and supreme arbiter (player character)
- **DIAGNOSTIC DES DYSFONCTIONNEMENTS**: Problem analysis identifying six major systemic issues threatening civilization stability (decision paralysis, economic dysfunction, uncontrolled monopolies, improvised justice, centrifugal fragmentation, destabilizing innovation system)

These documents should be updated as the game evolves and strategic priorities shift.

### Geography and Settlements

- **La Confluence**: Main settlement at the confluence of two rivers (one azure blue, one green) in a mountain valley
- **Cercles de Vigile**: Sacred fire sites on mountain promontories (e.g., highest circle before the peaks)
- **Antres des Échos**: Underground colonies including Gouffre Humide (most mature, contains the ancient ruins)
- **Villages sur pilotis**: Stilt villages of the Enfants du Courant along rivers and at confluences
- **Village fortifié à l'embouchure**: Coastal fortified settlement at river mouth where freshwater meets saltwater sea. Houses the first Hall des Serments with four-member council. Serves as sentinel against the unknown from the sea.
- **Route-rivière sécurisée**: Secured river-route connecting the valley to the coastal village, with guard posts spaced one day's march apart. Each post contains warriors, supplies, sleeping quarters, emergency reserves, and an Autel des Pionniers with guardian flame. Encourages colonization along the route with protection, trade access (Passes-bien), and honor (names inscribed on Pioneers' Altars).
- Temporary hunting/gathering camps throughout the valley
