escape-the-valley 1.0.0__tar.gz

escape_the_valley-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+  pull_request:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: pytest --tb=short -q

escape_the_valley-1.0.0/.github/workflows/pages.yml

@@ -0,0 +1,50 @@
+name: Deploy site to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install site dependencies
+        working-directory: site
+        run: npm ci
+
+      - name: Build site
+        working-directory: site
+        run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

escape_the_valley-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

escape_the_valley-1.0.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# Game state
+.trail/
+
+# IDE
+.vscode/
+.idea/
+
+# Coverage
+htmlcov/
+.coverage
+coverage.xml
+
+# Ruff
+.ruff_cache/
+site/.astro/
+node_modules/
+site/dist/
+.polyglot-cache.json

escape_the_valley-1.0.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to Escape the Valley are documented here.
+
+## [1.0.0] - 2026-03-04
+
+### Added
+
+- Full-screen Textual TUI with camp actions, event choices, and route forks
+- Three GM profiles: Chronicler (spare), Fireside (default), Lantern-Bearer (weird)
+- Voice narration via local audio synthesis (optional)
+- XRPL Testnet ledger backpack: supply tokens, settlement receipts, parcels (optional)
+- Procedural world generation with seeded RNG for reproducible runs
+- Party traits, twist deck, and doctrine/taboo system
+- Maintenance windows (rest+repair combo) for breakdown resistance
+- Escape valves: hard ration, desperate repair, abandon cargo
+- Warning callouts toggle (`--callouts verbose|minimal`)
+- Oregon Trail-style death causes in trail ledger
+- Memory card system for GM narrative continuity
+- Supply cache discovery at nodes
+- Spoilage mechanic (food decays without salt)
+- Night travel danger (needs lantern oil)
+- Classic CLI mode (`trail new`, `trail play`)
+- Save/load with full backward compatibility
+- 316 tests, lint clean
+- Survival guide (`docs/survival-guide.md`)

escape_the_valley-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

escape_the_valley-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: escape-the-valley
+Version: 1.0.0
+Summary: Oregon Trail-style survival game powered by Ollama GM with XRPL ledger-backed inventory
+Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: game,ollama,survival,terminal,xrpl
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.70
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: voice
+Requires-Dist: voice-soundboard>=2.5; extra == 'voice'
+Provides-Extra: xrpl
+Requires-Dist: xrpl-py>=3.0; extra == 'xrpl'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/escape-the-valley/readme.png" width="400" alt="Ledger Trail: Escape the Valley">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/escape-the-valley/actions"><img src="https://github.com/mcp-tool-shop-org/escape-the-valley/workflows/CI/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/escape-the-valley/"><img src="https://img.shields.io/pypi/v/escape-the-valley" alt="PyPI"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License">
+  <a href="https://mcp-tool-shop-org.github.io/escape-the-valley/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
+</p>
+
+<p align="center">
+  <em>A survival game where the trail is the teacher and the ledger keeps you honest.</em>
+</p>
+
+---
+
+## What Is This?
+
+Escape the Valley is an Oregon Trail-style survival game that runs in your terminal. Lead a party of settlers through a procedurally generated wilderness. Manage food, water, wagon condition, and morale while navigating events, hazards, and hard choices.
+
+An optional AI Game Master (powered by Ollama) narrates your journey with three distinct storytelling voices. An optional XRPL Testnet ledger backpack tracks your supply changes as on-chain receipts — proof that you survived, or proof that you tried.
+
+## Quick Start
+
+```bash
+pip install escape-the-valley
+
+# Launch the full-screen TUI (recommended)
+trail tui --seed 42
+
+# Resume a saved game
+trail tui --continue
+
+# With AI narration (requires Ollama running locally)
+trail tui --seed 42 --voice
+
+# Without AI narration (deterministic mode)
+trail tui --seed 42 --gm-off
+```
+
+## How to Play
+
+Each turn you choose an action from camp:
+
+| Action | What It Does |
+|--------|-------------|
+| **Travel** | Move toward the valley exit. Costs food and water. Risk of breakdown and events. |
+| **Rest** | Heal the party, recover morale. Costs supplies but no progress. |
+| **Hunt** | Spend ammo for a chance at food. Better in forests and plains. |
+| **Repair** | Spend a spare part to fix the wagon. Critical for survival. |
+
+**Events** interrupt travel with choices (A/B/C). Cautious choices are safer but cost time. Bold choices are faster but risky. There's no always-right answer.
+
+**The wagon is everything.** If it breaks with no parts, the run is over. Keep it above half condition and do maintenance windows (rest then repair) for temporary breakdown resistance.
+
+**Pace** controls speed vs. safety. Steady is the default. Hard pace covers more ground but burns more supplies and breaks wagons faster.
+
+**Escape valves** (hard ration, desperate repair, abandon cargo) exist for emergencies. They have side effects and cooldowns — last resorts, not strategies.
+
+For deeper tips, see the [Survival Guide](docs/survival-guide.md).
+
+## GM Profiles
+
+The AI narrator shapes the tone, not the mechanics. All three profiles play the same game.
+
+- **Chronicler** — Grounded, practical, spare. Minimal folklore. Reports what happened.
+- **Fireside** — Serious campfire narrator. Subtle uncanny moments. The default.
+- **Lantern-Bearer** — Uncanny and liminal, but still grounded in consequences. The weird one.
+
+Set with `--gm-profile`: `trail tui --gm-profile lantern`
+
+## Ledger Backpack (Optional)
+
+The Ledger Backpack tracks your 5 core supplies (food, water, meds, ammo, parts) as tokens on the XRPL Testnet. Every town checkpoint records a settlement receipt on-chain. At the end of your run, your trail ledger includes transaction IDs anyone can verify.
+
+Completely optional. The game plays identically with it off (the default). Enable it from the L menu in the TUI or via CLI:
+
+```bash
+trail ledger enable
+trail ledger status
+trail ledger reconcile  # retry failed settlements
+```
+
+Requires `pip install -e ".[xrpl]"` for the `xrpl-py` dependency.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `trail tui` | Launch the full-screen Textual UI |
+| `trail new` | Start a new run (classic CLI mode) |
+| `trail play` | Continue a saved run (classic CLI mode) |
+| `trail status` | Show party, wagon, and supplies |
+| `trail journal` | Show recent journal entries |
+| `trail self-check` | Check game environment health |
+| `trail version` | Show version |
+| `trail ledger status` | Show backpack status |
+| `trail ledger enable` | Enable XRPL backpack |
+| `trail ledger disable` | Disable XRPL backpack |
+| `trail ledger settle` | Manually settle a checkpoint |
+| `trail ledger reconcile` | Retry failed settlements |
+| `trail ledger wallet` | Show wallet details |
+| `trail parcel list` | List received parcels |
+| `trail parcel accept <id>` | Accept a pending parcel |
+
+## Warning Callouts
+
+By default, the game shows verbose warnings to help new players spot danger early. Experienced players can switch to minimal mode, which only shows cliff-edge warnings (last-moment, critical threats):
+
+```bash
+trail tui --callouts minimal
+trail new --callouts minimal
+```
+
+## Requirements
+
+- Python 3.11+
+- Ollama (optional, for AI narration)
+- xrpl-py (optional, for ledger backpack)
+
+## Security
+
+No telemetry. No accounts. All network features (Ollama, XRPL) are opt-in and disabled by default. XRPL operations use Testnet only. See [SECURITY.md](SECURITY.md) for the full threat model.
+
+## License
+
+MIT
+
+Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

escape_the_valley-1.0.0/README.es.md

@@ -0,0 +1,134 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.md">English</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/escape-the-valley/readme.png" width="400" alt="Ledger Trail: Escape the Valley">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/escape-the-valley/actions"><img src="https://github.com/mcp-tool-shop-org/escape-the-valley/workflows/CI/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License">
+  <img src="https://img.shields.io/badge/version-1.0.0-green" alt="Version">
+  <a href="https://mcp-tool-shop-org.github.io/escape-the-valley/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
+</p>
+
+<p align="center">
+  <em>A survival game where the trail is the teacher and the ledger keeps you honest.</em>
+</p>
+
+---
+
+## ¿Qué es esto?
+
+Escape the Valley es un juego de supervivencia al estilo de Oregon Trail que se ejecuta en tu terminal. Dirige un grupo de colonos a través de un terreno generado aleatoriamente. Administra alimentos, agua, el estado del carro y la moral, mientras navegas por eventos, peligros y decisiones difíciles.
+
+Un narrador de inteligencia artificial (IA) opcional (impulsado por Ollama) narra tu viaje con tres voces narrativas distintas. Una "mochila" opcional de registro de la red de pruebas XRPL rastrea tus cambios de suministros como recibos en la cadena de bloques, una prueba de que sobreviviste, o una prueba de que lo intentaste.
+
+## Guía de inicio rápido
+
+```bash
+pip install -e ".[dev]"
+
+# Launch the full-screen TUI (recommended)
+trail tui --seed 42
+
+# Resume a saved game
+trail tui --continue
+
+# With AI narration (requires Ollama running locally)
+trail tui --seed 42 --voice
+
+# Without AI narration (deterministic mode)
+trail tui --seed 42 --gm-off
+```
+
+## Cómo jugar
+
+En cada turno, eliges una acción desde el campamento:
+
+| Acción | Lo que hace |
+|--------|-------------|
+| **Travel** | Avanza hacia la salida del valle. Consume alimentos y agua. Riesgo de avería y eventos. |
+| **Rest** | Restaura la moral del grupo. Consume suministros, pero no avanza. |
+| **Hunt** | Usa munición para tener una oportunidad de obtener alimentos. Es más efectivo en bosques y llanuras. |
+| **Repair** | Usa una pieza de repuesto para reparar el carro. Es crucial para la supervivencia. |
+
+**Eventos:** Interrumpen el viaje con opciones (A/B/C). Las opciones cautelosas son más seguras, pero consumen tiempo. Las opciones audaces son más rápidas, pero arriesgadas. No siempre hay una respuesta correcta.
+
+**El carro es lo más importante.** Si se avería y no tienes piezas de repuesto, el juego termina. Mantén su estado por encima de la mitad y realiza mantenimientos (descansa y luego repara) para una resistencia temporal a las averías.
+
+**Ritmo:** Controla la velocidad frente a la seguridad. El ritmo constante es el predeterminado. Un ritmo rápido cubre más terreno, pero consume más suministros y avería los carros más rápido.
+
+**Válvulas de escape** (racionamiento extremo, reparación desesperada, abandonar carga) existen para emergencias. Tienen efectos secundarios y tiempos de recuperación; son un último recurso, no una estrategia.
+
+Para obtener más consejos, consulta la [Guía de Supervivencia](docs/survival-guide.md).
+
+## Perfiles del Narrador (IA)
+
+El narrador de IA define el tono, no la mecánica del juego. Los tres perfiles juegan el mismo juego.
+
+- **Chronicler (Cronista):** Práctico, directo y conciso. Mínimo folclore. Informa sobre lo que sucedió.
+- **Fireside (Junto al Fuego):** Narrador serio, como si estuvieras junto a una fogata. Tiene momentos sutiles e inquietantes. Es el predeterminado.
+- **Lantern-Bearer (Portador de la Linterna):** Inquietante y enigmático, pero aún arraigado en las consecuencias. Es el más extraño.
+
+Configura con `--gm-profile`: `trail tui --gm-profile lantern`
+
+## Mochila de Registro (Opcional)
+
+La mochila de registro rastrea tus 5 suministros principales (alimentos, agua, medicamentos, munición, piezas) como tokens en la red de pruebas XRPL. Cada punto de control de la ciudad registra un recibo de asentamiento en la cadena de bloques. Al final de tu partida, tu registro incluye los ID de transacción que cualquier persona puede verificar.
+
+Completamente opcional. El juego se juega de la misma manera con ella desactivada (que es la opción predeterminada). Actívala desde el menú L en la interfaz de usuario de texto o a través de la línea de comandos:
+
+```bash
+trail ledger enable
+trail ledger status
+trail ledger reconcile  # retry failed settlements
+```
+
+Requiere `pip install -e ".[xrpl]"` para la dependencia `xrpl-py`.
+
+## Comandos
+
+| Comando | Descripción |
+|---------|-------------|
+| `trail tui` | Inicia la interfaz de usuario de texto en pantalla completa |
+| `trail new` | Comienza una nueva partida (modo clásico de línea de comandos) |
+| `trail play` | Continúa una partida guardada (modo clásico de línea de comandos) |
+| `trail status` | Muestra el estado del grupo, el carro y los suministros |
+| `trail journal` | Muestra las entradas recientes del diario |
+| `trail self-check` | Verifica el estado del entorno del juego |
+| `trail version` | Muestra la versión |
+| `trail ledger status` | Muestra el estado de la mochila |
+| `trail ledger enable` | Activa la mochila XRPL |
+| `trail ledger disable` | Desactiva la mochila XRPL |
+| `trail ledger settle` | Realiza manualmente un asentamiento en un punto de control |
+| `trail ledger reconcile` | Reintenta asentamientos fallidos |
+| `trail ledger wallet` | Muestra los detalles de la billetera |
+| `trail parcel list` | Lista los paquetes recibidos |
+| `trail parcel accept <id>` | Acepta un paquete pendiente |
+
+## Advertencias
+
+Por defecto, el juego muestra advertencias detalladas para ayudar a los nuevos jugadores a identificar el peligro desde el principio. Los jugadores experimentados pueden cambiar al modo mínimo, que solo muestra las advertencias de "borde del precipicio" (amenazas críticas de último momento):
+
+```bash
+trail tui --callouts minimal
+trail new --callouts minimal
+```
+
+## Requisitos
+
+- Python 3.11 o superior
+- Ollama (opcional, para la narración con inteligencia artificial)
+- xrpl-py (opcional, para la función de "ledger backpack")
+
+## Seguridad
+
+No se recopilan datos de telemetría. No se utilizan cuentas. Todas las funciones de red (Ollama, XRPL) son opcionales y están desactivadas por defecto. Las operaciones de XRPL solo utilizan la red de pruebas (Testnet). Consulte el archivo [SECURITY.md](SECURITY.md) para obtener información completa sobre el modelo de amenazas.
+
+## Licencia
+
+MIT
+
+Desarrollado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

escape_the_valley-1.0.0/README.fr.md

@@ -0,0 +1,134 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.md">English</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/escape-the-valley/readme.png" width="400" alt="Ledger Trail: Escape the Valley">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/escape-the-valley/actions"><img src="https://github.com/mcp-tool-shop-org/escape-the-valley/workflows/CI/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License">
+  <img src="https://img.shields.io/badge/version-1.0.0-green" alt="Version">
+  <a href="https://mcp-tool-shop-org.github.io/escape-the-valley/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
+</p>
+
+<p align="center">
+  <em>A survival game where the trail is the teacher and the ledger keeps you honest.</em>
+</p>
+
+---
+
+## Qu'est-ce que c'est ?
+
+Escape the Valley est un jeu de survie de type Oregon Trail qui fonctionne dans votre terminal. Guidez un groupe de colons à travers une nature générée aléatoirement. Gérez la nourriture, l'eau, l'état du chariot et le moral, tout en gérant les événements, les dangers et les choix difficiles.
+
+Un Maître du Jeu IA optionnel (alimenté par Ollama) raconte votre aventure avec trois voix narratives distinctes. Un "sac à dos" de registre XRPL optionnel suit les changements de vos provisions sous forme de reçus sur la blockchain, prouvant que vous avez survécu, ou que vous avez essayé.
+
+## Démarrage rapide
+
+```bash
+pip install -e ".[dev]"
+
+# Launch the full-screen TUI (recommended)
+trail tui --seed 42
+
+# Resume a saved game
+trail tui --continue
+
+# With AI narration (requires Ollama running locally)
+trail tui --seed 42 --voice
+
+# Without AI narration (deterministic mode)
+trail tui --seed 42 --gm-off
+```
+
+## Comment jouer
+
+À chaque tour, vous choisissez une action au camp :
+
+| Action | Ce que cela fait |
+|--------|-------------|
+| **Travel** | Avancez vers la sortie de la vallée. Coûte de la nourriture et de l'eau. Risque de panne et d'événements. |
+| **Rest** | Soignez le groupe, améliorez le moral. Coûte des provisions, mais ne fait pas progresser. |
+| **Hunt** | Utilisez des munitions pour avoir une chance d'obtenir de la nourriture. Plus efficace dans les forêts et les plaines. |
+| **Repair** | Utilisez une pièce de rechange pour réparer le chariot. Essentiel pour la survie. |
+
+**Les événements** interrompent le voyage et proposent des choix (A/B/C). Les choix prudents sont plus sûrs, mais coûtent du temps. Les choix audacieux sont plus rapides, mais risqués. Il n'y a pas toujours de bonne réponse.
+
+**Le chariot est essentiel.** S'il tombe en panne et que vous n'avez plus de pièces, la partie est terminée. Maintenez-le en bon état (plus de la moitié) et effectuez des périodes de maintenance (repos puis réparation) pour une résistance temporaire aux pannes.
+
+**Le rythme** contrôle la vitesse par rapport à la sécurité. Le rythme normal est le réglage par défaut. Un rythme rapide couvre plus de terrain, mais consomme plus de provisions et abîme les chariots plus rapidement.
+
+Des **solutions de secours** (rations minimales, réparation désespérée, abandon de la cargaison) existent en cas d'urgence. Elles ont des effets secondaires et des temps de recharge ; ce sont des solutions de dernier recours, pas des stratégies.
+
+Pour obtenir des conseils plus approfondis, consultez le [Guide de survie](docs/survival-guide.md).
+
+## Profils du Maître du Jeu
+
+Le narrateur IA façonne le ton, pas les mécanismes. Les trois profils jouent le même jeu.
+
+- **Chronicler** — Pragmatique, concis, terre-à-terre. Folklore minimal. Décrit ce qui s'est passé.
+- **Fireside** — Narrateur de conte de feu sérieux. Moments subtils et étranges. Le réglage par défaut.
+- **Lantern-Bearer** — Étrange et liminal, mais toujours ancré dans les conséquences. Le plus bizarre.
+
+Définissez avec `--gm-profile` : `trail tui --gm-profile lantern`
+
+## Sac à dos de registre (Optionnel)
+
+Le sac à dos de registre suit vos 5 principales provisions (nourriture, eau, médicaments, munitions, pièces) sous forme de jetons sur le réseau de test XRPL. Chaque point de contrôle de la ville enregistre un reçu de transaction sur la blockchain. À la fin de votre partie, votre registre de parcours comprend les identifiants de transaction que toute personne peut vérifier.
+
+Entièrement optionnel. Le jeu se déroule de la même manière avec ou sans. Activez-le depuis le menu L dans l'interface utilisateur en texte ou via la ligne de commande :
+
+```bash
+trail ledger enable
+trail ledger status
+trail ledger reconcile  # retry failed settlements
+```
+
+Nécessite `pip install -e ".[xrpl]"` pour la dépendance `xrpl-py`.
+
+## Commandes
+
+| Commande | Description |
+|---------|-------------|
+| `trail tui` | Lance l'interface utilisateur en texte en plein écran |
+| `trail new` | Démarre une nouvelle partie (mode CLI classique) |
+| `trail play` | Continue une partie sauvegardée (mode CLI classique) |
+| `trail status` | Affiche le groupe, le chariot et les provisions |
+| `trail journal` | Affiche les entrées récentes du journal |
+| `trail self-check` | Vérifie l'état de l'environnement du jeu |
+| `trail version` | Affiche la version |
+| `trail ledger status` | Affiche l'état du sac à dos |
+| `trail ledger enable` | Active le sac à dos XRPL |
+| `trail ledger disable` | Désactive le sac à dos XRPL |
+| `trail ledger settle` | Effectue manuellement un enregistrement à un point de contrôle |
+| `trail ledger reconcile` | Réessaie les enregistrements infructueux |
+| `trail ledger wallet` | Affiche les détails du portefeuille |
+| `trail parcel list` | Liste les colis reçus |
+| `trail parcel accept <id>` | Accepte un colis en attente |
+
+## Avertissements
+
+Par défaut, le jeu affiche des avertissements détaillés pour aider les nouveaux joueurs à repérer les dangers dès le début. Les joueurs expérimentés peuvent passer en mode minimal, qui n'affiche que les avertissements de seuil critique (menaces de dernière minute) :
+
+```bash
+trail tui --callouts minimal
+trail new --callouts minimal
+```
+
+## Exigences
+
+- Python 3.11+
+- Ollama (facultatif, pour la narration par IA)
+- xrpl-py (facultatif, pour le "ledger backpack")
+
+## Sécurité
+
+Aucune télémétrie. Aucun compte. Toutes les fonctionnalités réseau (Ollama, XRPL) sont facultatives et désactivées par défaut. Les opérations XRPL utilisent uniquement le réseau de test. Consultez le fichier [SECURITY.md](SECURITY.md) pour l'analyse complète des risques.
+
+## Licence
+
+MIT
+
+Développé par <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>