civjdr/CLAUDE.md

# 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
- No contact yet between player civilizations, but competition/conflict expected eventually
- Players develop unique technologies and political systems for competitive advantage

## Repository Structure

- **Background/**: Contains all game documentation
  - `Background.md`: Complete game transcript - Discord conversations between player (Rubanc) and GM (Arthur) with narrative posts and player choices (very large file, 130KB, 1012 lines)
  - `OBJECTIFS STRATÉGIQUES - CIVILISATION DE LA CONFLUENCE.md`: **Player strategy document** - planned objectives organized by timeframe (court/moyen/long terme)
  - `Le Système Politique  L'Oligarchie Consociationnelle des Cinq Castes.md`: **Player strategy document** - detailed political system design for the five-caste oligarchy
  - `DIAGNOSTIC DES DYSFONCTIONNEMENTS SYSTÉMIQUES.md`: **Player strategy document** - analysis of systemic problems to resolve for civilization functionality

**Key Distinction:** Background.md is the actual game play-by-post transcript. The other three files are the player's 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 security force, conduct investigations and maintain order
- **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
- **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
- **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
- **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
- **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
- **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, translucent artifacts, sophisticated carving)
- **Grande Fresque**: Massive multilayered fresco depicting cosmology, sun worship, mysterious giants, and unknown animals
- Civilization apparently died out from unknown causes (miasmas in lower levels, no signs of violence)
- Ruins partially inaccessible due to flooding, toxic gases, and cave-ins
- Now pilgrimage site for Ailes-Grises, source of theological study and anxiety about similar fate

## Working with This Repository

### Reading the Background.md File

Background.md is the complete game transcript (130KB, 1012 lines). It contains:
- Discord conversation format between Arthur (GM) and Rubanc (player)
- Narrative posts from Arthur describing situations and consequences
- Player choices (often with "Choix:" markers) and custom responses ("autres [libre]")
- Meta-commentary in brackets about game mechanics and playtesting

**Technical notes:**
- 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
- File grows as the game continues - check line count with `wc -l`

### Language

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

### 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
- Temporary hunting/gathering camps throughout the valley