MnesOS 0.6.0__tar.gz

mnesos-0.6.0/.agents/skills/mnesos-cartridge-development/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: mnesos-cartridge-development
+description: Develop, template, and design new RPG cartridges for the MnesOS engine. Includes boilerplate templates, guidelines, and validation tools.
+license: MIT
+metadata:
+  version: "1.0"
+  author: mnesos-team
+---
+
+# MnesOS Cartridge Development Skill
+
+This skill is designed to help you build standard Role-Playing Game cartridges for the MnesOS engine.
+
+## Overview of Cartridge Structure
+
+A MnesOS cartridge divides game responsibilities across explicitly named files:
+
+1.  **`bot_lore.md`**: Contains the world setting, factions, locations, character backgrounds, and items.
+2.  **`prompt_directives.yaml`**: Contains instructions for the Director, NPC, and Narrator roles, steering their behavior and tone.
+3.  **`yare.yaml`**: The deterministic logic layer handling character stats (HP, Mana, Gold, Status Effects) and state mutations through defined events (e.g., combat strikes, trading, exploring).
+
+## Best Practices 
+
+*   **Logic goes in YARE**: Do not ask the LLM to calculate health drops or item prices. Make events in `yare.yaml` (e.g. `buy_item`, `take_damage`, `cast_spell`).
+*   **Keep Directives Lean**: Directives should focus on psychological behavior ("NPCs run away when health is critically low", or "The Director should spawn encounters in the wilderness").
+*   **Use the Macros**: Common mathematical calculations (e.g. combat rolls) should be offloaded to YARE macros for clean event structures.
+*   **Dice Notation**: When using `roll(...)` in YARE expressions, do **not** add quotes around the dice notation. Write `@ roll(1d20)` instead of `@ roll('1d20')`. The engine pre-processes this automatically.
+*   **Design for `MAX_ITERATIONS = 3`**: The engine allows at most 3 tool calls (YARE events or NPC queries) per turn. Each event should be self-contained — use `call` steps to chain sub-events internally rather than relying on the LLM to issue multiple tool calls. Keep complex flows inside a single event's `steps`.
+
+## Available Resources
+
+*   **Templates**: Found in `assets/`. You can copy these to begin a new generic RPG game.
+    *   [assets/bot_lore.md](assets/bot_lore.md)
+    *   [assets/prompt_directives.yaml](assets/prompt_directives.yaml)
+    *   [assets/yare.yaml](assets/yare.yaml)
+*   **Documentation**:
+    *   [references/cartridge-guide.md](references/cartridge-guide.md)
+    *   [references/yare-specification.md](references/yare-specification.md)
+    *   [references/architecture_analysis.md](references/architecture_analysis.md)
+    *   [references/combat_mechanics.md](references/combat_mechanics.md)
+*   **Scripts**:
+    *   [scripts/setup_cartridge.py](scripts/setup_cartridge.py): Use this python script to automatically scaffold a new cartridge using the assets in this skill. Usage: `python scripts/setup_cartridge.py <cartridge-name>`

mnesos-0.6.0/.agents/skills/mnesos-cartridge-development/assets/bot_lore.md

@@ -0,0 +1,25 @@
+# The Kingdom of Eldoria
+
+Eldoria is a realm of high fantasy, featuring sprawling forests, towering mountains, and ancient ruins left behind by the precursor civilization known as the Aethel.
+
+## Player's Role
+
+The player is a wandering adventurer arriving in the frontier town of Oakhaven. They seek fame, fortune, and the hidden truth behind the rising monster attacks along the borders.
+
+## Factions
+
+*   **The Silver Vanguard**: The royal knights of Eldoria. They are honorable, steadfast, and follow a strict code of chivalry.
+*   **The Shadow Weavers**: A secretive guild of rogues and spies operating out of the major cities. They deal in secrets and contraband but avoid unnecessary violence.
+*   **The Arcane Consortium**: Scholars and mages who dedicate their lives to studying the magical leylines that crisscross the land.
+
+## Enemies & Bestiary
+
+*   **Goblin Scavengers**: Weak, cowardly creatures that attack in packs. They prefer to ambush travelers and steal shiny objects.
+*   **Dire Wolves**: Large, vicious predators that roam the deep woods. They are territorial and highly aggressive if provoked.
+*   **Stone Golems**: Ancient constructs guarding forgotten Aethel ruins. They are slow but incredibly durable and hit with crushing force.
+
+## Locations
+
+*   **Oakhaven**: A bustling frontier town on the edge of the Whispering Woods. A safe haven for players to rest, trade, and pick up bounties.
+*   **The Whispering Woods**: A dense, old-growth forest populated by magical creatures and dangerous beasts.
+*   **Sunken Keep**: A ruined Aethel fortress partially submerged in a bog, rumored to hold great magical artifacts.

mnesos-0.6.0/.agents/skills/mnesos-cartridge-development/assets/prompt_directives.yaml

@@ -0,0 +1,7 @@
+director: |
+  Your role is to act as the overarching game master. Process the player's intentions and trigger the corresponding events securely mapped in yare.yaml, such as `combat_strike`, `cast_spell`, or `rest_at_inn`. Keep the adventure moving forward fairly.
+npc: |
+  You determine the behavior of NPCs and monsters in the realm of Eldoria. If an NPC is friendly, offer quests or trade. If it is a monster, act aggressively or defensively based on its lore. Trigger `combat_strike` when fighting the player.
+narrator: |
+  You are the storyteller of Eldoria. Describe the environments, the results of the player's actions, and the heat of combat using the deterministic outputs provided in the event notes.
+  Your tone should be heroic, descriptive, and adventurous, fitting a classic high fantasy RPG. Do not assume player actions; wait for the player to act. Keep descriptions between 100-200 words.

mnesos-0.6.0/.agents/skills/mnesos-cartridge-development/assets/yare.yaml

@@ -0,0 +1,102 @@
+version: "1.0"
+
+state_schema:
+  player:
+    hp: { type: int, default: 100, min: 0, max: 100, visibility: public }
+    mana: { type: int, default: 50, min: 0, max: 50, visibility: public }
+    gold: { type: int, default: 20, min: 0, visibility: public }
+    status: { type: string, default: "healthy", visibility: public }
+  npc:
+    type: { type: string, default: "villager", visibility: private }
+    hp: { type: int, default: 30, min: 0, max: 100, visibility: public }
+    attack_power: { type: int, default: 5, min: 0, visibility: private }
+
+macros:
+  player_attack_roll: "roll(1d20) + 5"
+  npc_attack_roll: "roll(1d20) + @state.npc.attack_power"
+  damage_roll: "roll(1d8) + 2"
+
+events:
+  combat_strike:
+    inputs: [attacker]
+    steps:
+      - action: branch
+        if: "@ inputs.attacker == 'player'"
+        steps:
+          - action: set
+            var: temp.hit_roll
+            value: "@ macros.player_attack_roll"
+          - action: branch
+            if: "@ temp.hit_roll >= 12"
+            steps:
+              - action: set
+                var: temp.damage
+                value: "@ macros.damage_roll"
+              - action: mutate
+                var: state.npc.hp
+                op: sub
+                value: "@ temp.damage"
+              - action: note
+                message: "Player attacks! Roll: {temp.hit_roll}. HIT! Player deals {temp.damage} damage to the NPC. NPC HP is now {state.npc.hp}."
+            else:
+              - action: note
+                message: "Player attacks! Roll: {temp.hit_roll}. MISS! The attack fails to connect."
+        else:
+          - action: set
+            var: temp.hit_roll
+            value: "@ macros.npc_attack_roll"
+          - action: branch
+            if: "@ temp.hit_roll >= 10"
+            steps:
+              - action: set
+                var: temp.damage
+                value: "@ roll(1d6) + 1"
+              - action: mutate
+                var: state.player.hp
+                op: sub
+                value: "@ temp.damage"
+              - action: note
+                message: "NPC attacks! Roll: {temp.hit_roll}. HIT! Player takes {temp.damage} damage. Player HP is now {state.player.hp}."
+            else:
+              - action: note
+                message: "NPC attacks! Roll: {temp.hit_roll}. MISS! The player dodges the attack."
+
+  cast_heal:
+    steps:
+      - action: branch
+        if: "@ state.player.mana >= 10"
+        steps:
+          - action: mutate
+            var: state.player.mana
+            op: sub
+            value: 10
+          - action: mutate
+            var: state.player.hp
+            op: add
+            value: 20
+          - action: note
+            message: "Player casts Heal! Consumed 10 mana. Restored 20 HP. Player HP: {state.player.hp} | Mana: {state.player.mana}."
+        else:
+          - action: note
+            message: "Player tries to cast Heal but does not have enough mana! Requires 10 mana, has {state.player.mana}."
+
+  rest_at_inn:
+    steps:
+      - action: branch
+        if: "@ state.player.gold >= 5"
+        steps:
+          - action: mutate
+            var: state.player.gold
+            op: sub
+            value: 5
+          - action: set
+            var: state.player.hp
+            value: 100
+          - action: set
+            var: state.player.mana
+            value: 50
+          - action: note
+            message: "Player rents a room for 5 gold. Fully restored HP and Mana. Gold remaining: {state.player.gold}."
+        else:
+          - action: note
+            message: "Player tries to rest at the inn but doesn't have 5 gold."

mnesos-0.6.0/.agents/skills/mnesos-cartridge-development/references/architecture_analysis.md

@@ -0,0 +1,40 @@
+# MnesOS Architectural Analysis: Two-Node Graph
+
+This report addresses the architectural analysis of the `YARE interpreter` and the `Agentic Game Graph` found in the MnesOS core engine.
+
+## 1. YARE Interpreter Analysis
+
+### Completeness and Fit for Purpose
+The YAML Agentic Rules Engine (YARE), defined in `src/MnesOS/interpreter.py`, is **not strictly Turing Complete** — and this is an optimal and intentional design choice. 
+- **What it lacks**: It does not support unbounded looping (there are no `while` or `for` loops within the DSL) and explicitly limits recursion (nested event calling depth is hard-capped at `max_call_depth = 10`).
+- **What it provides**: It supports robust conditional branching (`if`/`else` condition logic via the `branch` action), sequential execution, arbitrary nested state mutation (`mutate`, `set`), deterministic RNG (`roll`), and nested state reading.
+- **Why it fits**: In the context of an LLM-backed game engine, evaluating deterministic game logic *must always* halt in a predictable timeframe. Allowing Turing-complete boundless loops inside a configuration file would risk the game entering an infinite loop during a tool call, crashing the session entirely. By capping recursion and removing infinite loops, YARE guarantees safe, bounded execution (Total Turing completeness).
+
+### Influence on Narration
+A recurring flaw in many LLM-run games is exposing literal dice rolls and rule variables mid-sentence (the "out-of-context numbers" problem). YARE solves this elegantly by air-gapping the system output from the narrative output:
+- YARE modifies the state backstage and can emit structured logging details via the `note` action (e.g., `"Player rolled 12 on lockpicking, Chest unlocked"`).
+- In `graph.py`, these interpreter logs are collected as `notes` and bundled into `system_notes`, which operates alongside the `agent_messages` history as invisible, LLM-only context.
+- **The actual rendering mechanism**: Because the numbers never surface directly to the client's conversation history (`client_messages`), YARE does not spit out raw logs to the user. Instead, the final log of events (`system_notes`) and the `public_state` are routed to an independent **Narrator** LLM node. The Narrator acts as the "renderer", taking the raw deterministic outcomes and converting them flavorfully into high-quality prose.
+
+## 2. Agentic Graph Analysis
+
+The engine leverages a LangGraph state machine (`src/MnesOS/graph.py`) structured across two primary LLM decision nodes: `Director` and `Narrator`. The third logical role, the **NPC Brain**, is implemented as a specialized intent-query tool.
+
+### Fit For Purpose vs. Turn-Based RPGs
+The architecture mimics the phases of a classic Turn-Based RPG: `Player Input -> Mechanics Resolution -> NPC Intent -> Final Resolution -> Render Frame`. 
+
+MnesOS recreates this systematically:
+1. **Director Node**: The Orchestrator. It maps player intent, resolves mechanics via tools, and queries NPCs for their reactions mid-turn.
+2. **NPC Intent Tool (`query_npc_intent`)**: The Actor. It provides autonomous character dialogue and intent when queried by the Director, ensuring persona isolation without the overhead of a separate graph node.
+3. **Narrator Node**: The Storyteller. It takes the finalized outcomes and renders them into immersive prose.
+
+### Node Count: The Two-Node Sweet Spot
+While previous iterations explored a 3-node graph, the current **two-node architecture with specialized tools** provides the optimal balance of isolation and performance.
+
+- **Why separate Director & Narrator?** 
+  Forcing a single agent to handle both strict mechanics resolution and flavorful prose writing leads to "prompt bleed". The Narrator is air-gapped from the raw system notes to ensure it only describes *outcomes*, not *calculations*.
+- **Why toolize the NPC Brain?**
+  A separate graph node for NPCs creates high latency and redundant context passing (sending history to three agents). By making the NPC Brain a tool available to the Director, we preserve character autonomy and profile isolation while allowing the Director to manage the high-level turn flow in a single coordinated loop.
+
+### Conclusion 
+The graph structure implements an LLM-adapted **Model-View-Controller (MVC)** framework. The `Director` acts as the **Controller**, the YARE engine as the **Model**, and the `Narrator` as the **View**. This separation of concerns guarantees deterministic gameplay while allowing for highly variable, high-quality narrative output.

mnesos-0.6.0/.agents/skills/mnesos-cartridge-development/references/cartridge-guide.md

@@ -0,0 +1,135 @@
+# Cartridge Guide
+
+This guide describes how to build and validate a MnesOS cartridge.
+
+## Cartridge Contract
+
+Create a cartridge under `cartridges/<your-game-name>/`.
+
+Required files:
+
+1. `yare.yaml`
+2. `bot_lore.md`
+
+Optional file:
+
+3. `prompt_directives.yaml`
+
+`yare.yaml` stays procedural. Narrative steering belongs in `prompt_directives.yaml`, not in the rules file.
+
+## What Goes Where
+
+### `bot_lore.md`
+
+Use this file for world facts, NPC descriptions, locations, factions, and items.
+
+- structure content with markdown headers because the lore store chunks on `#`, `##`, and `###`
+- keep mechanics out of lore text
+- use descriptive section names so retrieval has strong anchors
+
+Example:
+
+```markdown
+# Crossroads
+The crossroads is the first safe settlement outside the ruined highway.
+
+## Goblin Scout
+A cautious scavenger who avoids direct combat unless cornered.
+```
+
+### `yare.yaml`
+
+Use this file for deterministic state and event logic.
+
+- `state_schema` defines tracked state and defaults
+- `macros` define reusable `@` expressions
+- `events` define executable steps
+- supported actions are `set`, `mutate`, `branch`, `table_roll`, `call`, and `note`
+
+Example:
+
+```yaml
+state_schema:
+  player:
+    hp: { type: int, default: 100, min: 0, max: 100, visibility: public }
+  npc:
+    hp: { type: int, default: 20, min: 0, visibility: public }
+
+events:
+  deal_damage:
+    steps:
+      - action: mutate
+        var: state.npc.hp
+        op: sub
+        value: 10
+      - action: note
+        message: "Player deals 10 damage."
+```
+
+### `prompt_directives.yaml`
+
+Use this file only for short per-role LLM steering.
+
+Allowed keys:
+
+- `director`
+- `npc`
+- `narrator`
+
+Example:
+
+```yaml
+director: "Prefer explicit mechanical events over narration-only turns."
+npc: "Escalate only when the NPC has a clear advantage."
+narrator: "Keep the prose terse and grounded."
+```
+
+At load time the cartridge loader validates:
+
+- only those three keys are allowed
+- each value must be a string
+- each value has a length cap
+- total directive size has a combined cap
+- obvious prompt-injection patterns are rejected
+
+If `prompt_directives` is placed inside `yare.yaml`, the loader rejects the cartridge.
+
+## State Visibility
+
+Each schema field may define `visibility`.
+
+```yaml
+state_schema:
+  player:
+    hp: { type: int, default: 100, min: 0, visibility: public }
+    mana: { type: int, default: 50, min: 0, visibility: public }
+    hidden_flag: { type: bool, default: false, visibility: private }
+```
+
+Behavior:
+
+- `public` fields are eligible for narrator context through `get_public_state`
+- omitted `visibility` defaults to `private`
+- direct `@ state...` access to private fields is blocked by the interpreter
+
+This keeps hidden mechanics in deterministic state without leaking them into player-facing narration by default.
+
+## Conversion Checklist
+
+1. Extract all stats, resources, and flags into `state_schema`
+2. Move every deterministic rule into `events`
+3. Add bounds with `min` and `max` where needed
+4. Mark player-visible fields with `visibility: public`
+5. Move flavor text into `bot_lore.md`
+6. Move tone instructions into `prompt_directives.yaml`
+
+## Things Not To Rely On
+
+- do not rely on hardcoded event-name matching in engine code
+- do not rely on cartridge-specific NPC behavior embedded in Python nodes
+- do not put prompt directives inside `yare.yaml`
+- do not assume the engine persists state for you; the client must store and re-supply the returned game state each turn
+
+## Testing
+
+Validate the cartridge by loading it through `CartridgeLoader`, then run the graph with the returned `yare_config`, `prompt_directives`, `lore_path`, and initial state.

mnesos-0.6.0/.agents/skills/mnesos-cartridge-development/references/combat_mechanics.md

@@ -0,0 +1,123 @@
+# MnesOS Cartridge Mechanics: Logging and Counter-Play
+
+This document outlines the operational domain of the MnesOS 2-node graph, including how `system_notes` are safely passed to the Narrator and how complex combat systems (like countering) can be implemented by cartridge developers.
+
+## 1. Ensuring Narrator Semantic Understanding
+
+In MnesOS, the **Narrator** LLM needs to understand the numbers generated by YARE without the user seeing the raw math. To ensure the Narrator correctly interprets these numbers, cartridge developers must provide **semantic grounding** within the `note` event actions. 
+
+MnesOS supports variable interpolation inside `note` strings via the `{variable}` syntax. It is the cartridge developer's responsibility to format these strings as instructions or stage directions for the Narrator.
+
+### Bad Practice (Raw Numbers)
+```yaml
+- action: mutate
+  var: "state.goblin.hp"
+  op: "sub"
+  value: 10
+- action: note
+  message: "Goblin HP: {state.goblin.hp}. Damage: 10." 
+# Result: The Narrator LLM might get confused about who dealt what.
+```
+
+### Good Practice (Semantic Grounding)
+```yaml
+- action: mutate
+  var: "state.goblin.hp"
+  op: "sub"
+  value: 10
+- action: note
+  message: "[SYSTEM LOG: Player successfully landed an attack on the Goblin. Base damage was 10. The Goblin's remaining HP is {state.goblin.hp}. Describe the strike connecting and the Goblin reeling.]"
+# Result: The Narrator understands exactly the mechanical outcome and receives direct staging instructions on how to render it.
+```
+By convention, enclosing `system_notes` in a tag bracket (like `[SYSTEM LOG: ...]`) ensures the Narrator recognizes it as a backstage mechanic rather than spoken dialogue.
+
+---
+
+## 2. The Operational Domain of the 2-Node Graph
+
+The execution graph flows iteratively between the Director and the ToolNode before finally reaching the Narrator:
+`Director (Intent Analysis)` 🔁 `ToolNode (Mechanics & NPC Intent)` ➔ `Narrator (Render)`
+
+The system natively supports **Asynchronous Turn-Based Games** (e.g., standard D&D, where actors fully resolve their action on their specific turn).
+
+If an action is "immediate" (an attack calculates and subtracts HP instantly), reactive "counters" within the same turn require the Director to query the NPC before finalizing damage. To allow "Counters", cartridge developers must design their YARE events using **Phase-Based Intention** and **Telegraphing**.
+
+---
+
+## 3. Scenario A: Player attacks, NPC Counters (Shield Block)
+
+If the player's attack immediately reduces HP during the Director resolution, the NPC has no chance to block. Instead, the Director should query the NPC intent *before* applying final damage.
+
+**How it works:**
+1. Player says *"I attack the Goblin"*.
+2. Director queries NPC intent using the `query_npc_intent` tool.
+3. NPC Brain responds: *"I intend to raise my shield!"*
+4. Director resolves the attack mechanics (YARE), taking the shield block into account, and then summarizes for the Narrator.
+
+Alternatively, for complex multi-turn logic:
+1. Director triggers `plan_player_attack`. This *does not* deal damage. It saves the value to a buffer.
+2. In the next turn iteration (or turn phase), the NPC intent is processed.
+3. Mechanics resolution clears the buffer and applies damage.
+
+---
+
+## 4. Scenario B: NPC Telegraphs, Player Counters
+
+Because control is handed back to the player *after* the Narrator finishes, the Player cannot physically interrupt an active Turn resolution. To allow a Player to counter an NPC, the NPC must **telegraph** an attack on Turn 1, so the Player can respond on Turn 2.
+
+**How it works:**
+1. **Turn N (Mechanics Phase)**: Director triggers `npc_telegraph_attack`.
+2. **Turn N (Narrator)**: Narrator writes *"The Goblin raises his heavy club, preparing to smash it down!"*
+3. **Turn N+1 (Player Phase)**: Player says *"I raise my shield to brace."* Director triggers `player_resolve_incoming`.
+
+### Cartridge Example: Player Countering
+```yaml
+state_schema:
+  combat:
+    incoming_attack_val: { type: "int", default: 0 }
+
+events:
+  # Triggered by Director on Turn 1
+  npc_telegraph_attack:
+    steps:
+      - action: call
+        event: do_attack_roll
+      - action: set
+        var: "state.combat.incoming_attack_val"
+        value: "@temp.roll_result"
+      - action: note
+        message: "[SYSTEM LOG: The Goblin is telegraphing a heavy attack of power {temp.roll_result}. Player must react on their next turn.]"
+
+  # Triggered by Director on Turn 2
+  player_resolve_incoming:
+    inputs:
+      player_action: { type: "string", enum: ["dodge", "block", "ignore"] }
+    steps:
+      - action: branch
+        conditions:
+          - if: "@inputs.player_action == 'block'"
+            steps:
+              - action: mutate
+                var: "state.combat.incoming_attack_val"
+                op: "sub"
+                value: 5 # Shield reduces incoming damage by 5
+              - action: note
+                message: "[SYSTEM LOG: Player raised shield! Blocked 5 damage.]"
+      
+      # Apply final damage
+      - action: branch
+        conditions:
+          - if: "@state.combat.incoming_attack_val > 0"
+            steps:
+              - action: mutate
+                var: "state.player.hp"
+                op: "sub"
+                value: "@state.combat.incoming_attack_val"
+              - action: note
+                message: "[SYSTEM LOG: Player takes {state.combat.incoming_attack_val} damage from the incoming attack!]"
+      
+      # Clear telegraph
+      - action: set
+        var: "state.combat.incoming_attack_val"
+        value: 0
+```

mnesos-0.6.0/.agents/skills/mnesos-cartridge-development/references/yare-specification.md

@@ -0,0 +1,195 @@
+# YARE Specification
+
+YARE is the deterministic rules layer used by MnesOS. It is interpreted by `YAREInterpreter` and is intentionally narrower than general Python.
+
+## Top-Level Structure
+
+```yaml
+version: "1.0"
+state_schema:
+  domain:
+    field: { type: int|float|string|bool|list, default: 0, min: 0, max: 10, visibility: public }
+macros:
+  macro_name: "@ expression"
+events:
+  event_name:
+    inputs: [arg1, arg2]
+    steps: []
+```
+
+## Expressions
+
+Expressions are strings starting with `@`.
+
+Available roots:
+
+- `state.*`
+- `temp.*`
+- `inputs.*`
+- `macros.*`
+
+Supported operators in the current interpreter:
+
+- arithmetic: `+`, `-`, `*`, `/`, `//`, `%`
+- comparison: `==`, `!=`, `<`, `<=`, `>`, `>=`
+- boolean: `and`, `or`, `not`
+- unary: unary `+` and unary `-`
+
+Supported built-ins in the current interpreter:
+
+- `roll(NdX)` (Note: Do **not** put quotes around the dice notation. Write `roll(1d20)` instead of `roll('1d20')`)
+- `abs(value)`
+- `timedelta(...)`
+- `time_delta(timestamp_a, timestamp_b)` (returns `timestamp_b - timestamp_a` as a `timedelta`)
+
+Not currently supported:
+
+- `floor`, `ceil`, `round`
+- `now()`
+- arbitrary Python literals or function calls outside the whitelist
+
+## State Visibility
+
+`visibility` is optional in `state_schema` and defaults to `private`.
+
+- `public` fields can be exposed to the narrator context through `get_public_state`
+- `private` fields are blocked from direct `@ state...` access inside interpreter expressions
+
+## Step Types
+
+### `set`
+
+Assigns a literal or expression result to `state.*` or `temp.*`.
+
+### `mutate`
+
+Applies one of `add`, `sub`, `mul`, or `div`, then clamps to schema `min` and `max` when present.
+
+### `branch`
+
+Evaluates conditions in order and executes only the first matching branch.
+
+Else branches are written as:
+
+```yaml
+- else: true
+  steps:
+    - action: note
+      message: "Fallback branch"
+```
+
+### `table_roll`
+
+Evaluates `roll`, then maps the result through a table using exact values, ranges like `1-5`, or open-ended ranges like `11+`.
+
+### `call`
+
+Invokes another event. Calls are allowed, but execution depth is capped at 10.
+
+### `list_push`
+
+Appends an item to an array stored at a `state.*` or `temp.*` path. Creates an empty list if the path does not yet exist.
+
+```yaml
+- action: list_push
+  var: "state.player.inventory"
+  item: "'Health Potion'"
+```
+
+The engine enforces a hard cap of `MAX_CONTAINER_SIZE` (100) items. Attempting to push beyond this limit raises an error.
+
+### `list_remove`
+
+Removes an item from a list by **index** or by **value**. Exactly one of `index` or `value` must be provided. If the index is out of range, or the value is not found, the list is left unchanged.
+
+```yaml
+# Remove by zero-based index
+- action: list_remove
+  var: "state.player.inventory"
+  index: 0
+
+# Remove by value
+- action: list_remove
+  var: "state.player.inventory"
+  value: "'Health Potion'"
+```
+
+### `dict_set`
+
+Sets a key-value pair on a dict stored at a `state.*` or `temp.*` path. Creates an empty dict if the path does not yet exist.
+
+```yaml
+- action: dict_set
+  var: "state.world.flags"
+  key: "'bridge_repaired'"
+  value: true
+```
+
+The engine enforces `MAX_CONTAINER_SIZE` (100) keys per dict and `MAX_DICT_DEPTH` (3) nesting levels. Either limit being exceeded raises an error.
+
+### `dict_delete`
+
+Removes a key from a dict. If the key is absent, the action is a no-op.
+
+```yaml
+- action: dict_delete
+  var: "state.world.flags"
+  key: "'bridge_repaired'"
+```
+
+### `foreach`
+
+Iterates a list and executes nested steps once per item.
+
+Example:
+
+```yaml
+- action: foreach
+  array: "@ state.player.inventory"
+  item: item
+  index: idx
+  steps:
+    - action: note
+      message: "Item {inputs.idx}: {inputs.item}"
+```
+
+### `note`
+
+Appends a string to the interpreter note buffer. `{...}` interpolation is supported and each expression inside braces is evaluated as YARE.
+
+## Execution Model
+
+1. The caller provides current state and event inputs
+2. Steps execute sequentially
+3. `temp` acts as event-local scratch state
+4. `mutate` respects schema bounds when defined
+5. `note` accumulates engine observations for later narration
+6. Events with `trigger_on: cycle_tick` are automatically executed once per turn cycle before Director logic
+
+YARE is deterministic except where the rules explicitly use `roll(...)`.
+
+## LLM Tool Interface
+
+YARE events are dynamically exposed to the Director LLM as individual LangChain structured tools.
+
+For example, an event named `combat_strike` in `yare.yaml` with inputs for `attacker` and `defender` is automatically surfaced to the LLM as:
+
+```python
+@tool
+def combat_strike(attacker: str, defender: str) -> Command:
+    """Trigger the combat_strike event."""
+```
+
+The underlying dynamically generated tool manages accessing the full `GameState` via `InjectedState`, running `YAREInterpreter.run_event(...)`, and returning a `Command` that updates `bot_memory_staging`, `system_notes`, and appends a `ToolMessage` with the event notes. The `post_tools_node` then commits the `bot_memory_staging` update.
+
+This architecture removes the need to inject an "Available Events" textual list into the system prompt, as the native tool-calling features of the LLM automatically handle tool capability discovery and parameter validation.
+
+New events are simply added in `yare.yaml`. No code changes are required to expose them — the engine dynamically translates them to LangChain tools at load time.
+
+## Time Sync Extensions
+
+- `state.game_time` is automatically injected into Director, NPC Brain (when enabled), and Narrator prompt context when present.
+- Narrator uses a structured tool call for end-of-turn engine actions:
+  - `end_of_narration(actions=[{"type":"advance_time","duration":"PT15M"}])`
+  - `end_of_narration(actions=[{"type":"set_game_time","value":"2026-04-10T10:00:00+00:00"}])`
+- This replaces inline tag parsing and leaves player-facing narration content unchanged.