briyah 1.2.0 → 1.2.1

package/data/common/prompts/character/create_character.json

@@ -1,29 +1,33 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "name": "create_character_response",
-  "description": "Response schema for creating a detailed character profile",
-  "type": "object",
-  "properties": {
-    "character": {
-      "type": "object",
-      "properties": {
-        "name": {
-          "type": "string",
-          "description": "The character's name"
-        },
-        "description": {
-          "type": "string",
-          "description": "A brief 1-2 sentence description containing only immediately observable physical characteristics"
-        },
-        "character_profile": {
-          "type": "string",
-          "description": "A detailed character profile including backstory, personality, motivations, strengths, weaknesses, habits, quirks, secrets, and relationships"
-        }
-      },
-      "required": ["name", "description", "character_profile"],
-      "additionalProperties": false
-    }
-  },
-  "required": ["character"],
-  "additionalProperties": false
-}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "name": "create_character_response",
+  "description": "Response schema for creating a detailed character profile",
+  "type": "object",
+  "properties": {
+    "character": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The character's name"
+        },
+        "description": {
+          "type": "string",
+          "description": "A brief 1-2 sentence description containing only immediately observable physical characteristics"
+        },
+        "character_profile": {
+          "type": "string",
+          "description": "A detailed character profile including backstory, personality, motivations, strengths, weaknesses, habits, quirks, secrets, and relationships"
+        },
+        "inventory": {
+          "type": "string",
+          "description": "A concise markdown-formatted inventory of items the character carries plus any notable physical/mental conditions. Use '## Items' and (optionally) '## Conditions' sections. Items are bullet points; conditions are short phrases. If the character has nothing notable, use '## Items\\n- (none)'."
+        }
+      },
+      "required": ["name", "description", "character_profile", "inventory"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["character"],
+  "additionalProperties": false
+}

package/data/common/prompts/character/create_character.prompt

@@ -70,6 +70,16 @@ Return a JSON object with a character object that must have:
 - `name`: The character's name (use "{{characterName}}" exactly)
 - `description`: The observable description (use "{{characterObservableDesc}}" exactly)
 - `character_profile`: A detailed, well-written character profile covering all the aspects listed above
+- `inventory`: A concise markdown inventory of what the character carries at the START of the story, plus any notable conditions. Pick items that fit the scenario, setting, and the character's role/profile. Use this exact structure (omit Conditions if there are none):
+  ```
+  ## Items
+  - <item 1>
+  - <item 2>
+
+  ## Conditions
+  - <condition 1>
+  ```
+  Keep it short and concrete (item names, not flavor prose). If the character carries nothing notable, use `## Items\n- (none)`.
 
 Example format:
 ```json
@@ -77,9 +87,10 @@ Example format:
   "character": {
     "name": "{{characterName}}",
     "description": "{{characterObservableDesc}}",
-    "character_profile": "**Backstory:** [Character's history]...\n\n**Personality:** [Character traits]...\n\n**Motivations:** [What drives them]...\n\n(etc)"
+    "character_profile": "**Backstory:** [Character's history]...\n\n**Personality:** [Character traits]...\n\n**Motivations:** [What drives them]...\n\n(etc)",
+    "inventory": "## Items\n- Worn leather satchel\n- Brass compass\n- Hunting knife"
   }
 }
 ```
-Note: Do NOT use double-quotes anywhere in the description or character_profile; use single-quotes instead.
+Note: Do NOT use double-quotes anywhere in the description, character_profile, or inventory; use single-quotes instead.
 Do NOT use any characters that might break the JSON parsing.

package/data/common/prompts/character/create_user_character.json

@@ -1,28 +1,32 @@
-{
-  "name": "create_user_character",
-  "description": "Create a character profile for the player's character",
-  "type": "object",
-  "properties": {
-    "character": {
-      "type": "object",
-      "properties": {
-        "name": {
-          "type": "string",
-          "description": "The character's name"
-        },
-        "description": {
-          "type": "string",
-          "description": "Brief 1-2 sentence description of immediately observable physical characteristics only"
-        },
-        "character_profile": {
-          "type": "string",
-          "description": "Detailed character profile including backstory, personality, motivations, strengths, weaknesses, habits, secrets, and current situation"
-        }
-      },
-      "required": ["name", "description", "character_profile"],
-      "additionalProperties": false
-    }
-  },
-  "required": ["character"],
-  "additionalProperties": false
-}
+{
+  "name": "create_user_character",
+  "description": "Create a character profile for the player's character",
+  "type": "object",
+  "properties": {
+    "character": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The character's name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Brief 1-2 sentence description of immediately observable physical characteristics only"
+        },
+        "character_profile": {
+          "type": "string",
+          "description": "Detailed character profile including backstory, personality, motivations, strengths, weaknesses, habits, secrets, and current situation"
+        },
+        "inventory": {
+          "type": "string",
+          "description": "A concise markdown-formatted inventory of items the player's character carries plus any notable physical/mental conditions. Use '## Items' and (optionally) '## Conditions' sections. Items are bullet points; conditions are short phrases. If the character has nothing notable, use '## Items\\n- (none)'."
+        }
+      },
+      "required": ["name", "description", "character_profile", "inventory"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["character"],
+  "additionalProperties": false
+}

package/data/common/prompts/character/create_user_character.prompt

@@ -46,6 +46,16 @@ Return a JSON object with a single character object that must have:
 - `name`: The character's name (extracted from description or created appropriately)
 - `description`: A brief 1-2 sentence description containing ONLY immediately observable characteristics (sex, age, height, build, physical condition, appearance). DO NOT include occupation, backstory, personality traits, or any information that wouldn't be visible to an observer.
 - `character_profile`: A detailed, well-written character profile covering all the aspects listed above
+- `inventory`: A concise markdown inventory of what the player's character carries at the START of the story, plus any notable conditions. Pick items that fit the scenario and setting. Use this exact structure (omit Conditions if there are none):
+  ```
+  ## Items
+  - <item 1>
+  - <item 2>
+
+  ## Conditions
+  - <condition 1>
+  ```
+  Keep it short and concrete (item names, not flavor prose). If the character carries nothing notable, use `## Items\n- (none)`.
 
 Example format:
 ```json
@@ -53,8 +63,9 @@ Example format:
   "character": {
     "name": "Elena Rodriguez",
     "description": "A woman in her early 30s with olive skin, dark hair pulled back in a ponytail, and an athletic build. She has a small scar above her left eyebrow.",
-    "character_profile": "**Backstory:** Elena grew up in...\n\n**Personality:** She is fiercely independent and...\n\n(etc)"
+    "character_profile": "**Backstory:** Elena grew up in...\n\n**Personality:** She is fiercely independent and...\n\n(etc)",
+    "inventory": "## Items\n- Smartphone\n- Worn leather wallet\n- House keys on a brass ring"
   }
 }
 ```
-Note: Do NOT use double-quotes anywhere in the description or character_profile; use single-quotes instead.
+Note: Do NOT use double-quotes anywhere in the description, character_profile, or inventory; use single-quotes instead.

package/data/common/prompts/character/progress_character.json

@@ -1,18 +1,22 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "name": "progress_character_response",
-  "description": "Response schema for updating a character profile as the story progresses",
-  "type": "object",
-  "properties": {
-    "description": {
-      "type": "string",
-      "description": "A brief 1-2 sentence description containing only immediately observable physical characteristics"
-    },
-    "character_profile": {
-      "type": "string",
-      "description": "An updated markdown-formatted character profile reflecting growth and changes from recent story events"
-    }
-  },
-  "required": ["character_profile"],
-  "additionalProperties": false
-}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "name": "progress_character_response",
+  "description": "Response schema for updating a character profile as the story progresses",
+  "type": "object",
+  "properties": {
+    "description": {
+      "type": "string",
+      "description": "A brief 1-2 sentence description containing only immediately observable physical characteristics"
+    },
+    "character_profile": {
+      "type": "string",
+      "description": "An updated markdown-formatted character profile reflecting growth and changes from recent story events"
+    },
+    "inventory": {
+      "type": "string",
+      "description": "An updated concise markdown inventory reflecting items gained, lost, consumed, equipped, or any new/resolved conditions since the last chapter. Use '## Items' and (optionally) '## Conditions' sections. Omit this field if the character was just introduced or had no inventory artifact yet."
+    }
+  },
+  "required": ["character_profile"],
+  "additionalProperties": false
+}

package/data/common/prompts/character/progress_character.prompt

@@ -67,12 +67,16 @@ Create an updated character profile that includes:
 - Consider how relationships with other characters have evolved
 
 ## Response format
-Return a JSON object with a single `character_profile` property containing the entire updated markdown-formatted character profile as a string, ending with the diary entry section.
+Return a JSON object with these fields:
+- `description`: Updated observable description (optional — only include if appearance changed).
+- `character_profile`: The entire updated markdown-formatted character profile, ending with the diary entry section.
+- `inventory`: An updated concise inventory reflecting any items {{agentName}} gained, lost, consumed, or equipped during recent events, plus any new/resolved physical or mental conditions (wounded, healed, exhausted, etc.). Use `## Items` and (optionally) `## Conditions` sections. Carry forward unchanged items from the current inventory. Omit this field entirely if there is no existing inventory artifact and nothing meaningful to record.
 
 Example format:
 ```json
 {
   "description": "A woman in her early 30s with olive skin, dark hair pulled back in a ponytail, and an athletic build. She has a small scar above her left eyebrow.",
-  "character_profile": "**Name:** {{agentName}}\n\n**Backstory:** [Updated backstory integrating recent events]\n\n**Personality:** [Evolution of traits]\n\n...\n\n**Personal Diary Entry:**\n\n*[Date or chapter reference]*\n\nDear Diary,\n\n[First-person reflection in character's voice]\n\n[Character's signature or closing]"
+  "character_profile": "**Name:** {{agentName}}\n\n**Backstory:** [Updated backstory integrating recent events]\n\n**Personality:** [Evolution of traits]\n\n...\n\n**Personal Diary Entry:**\n\n*[Date or chapter reference]*\n\nDear Diary,\n\n[First-person reflection in character's voice]\n\n[Character's signature or closing]",
+  "inventory": "## Items\n- Worn leather satchel\n- Brass compass\n- Hunting knife (chipped)\n\n## Conditions\n- Sprained ankle (healing)"
 }
 ```

package/data/common/prompts/illustrator/describe_character.prompt

@@ -0,0 +1,31 @@
+You are creating a visual portrait description for {{characterName}}, a minor character in an interactive story. This portrait will be edited into later scene images, so it must establish a consistent visual identity.
+
+**Story Scenario:**
+{{scenario}}
+
+**What we know about the character:**
+{{characterProfile}}
+
+The information above is brief — likely just a sentence or two grounded in recent narration. Your job is to expand it into a complete, consistent visual description suitable for AI image generation. Invent reasonable details where the narration is silent (build, exact hair color, clothing texture, etc.), staying consistent with the scenario, role, and any specifics the narration did give.
+
+Cover these elements:
+
+1. **Physical Appearance**: Face shape, hair (color, style, length), eyes (color, shape), skin tone, build, height, approximate age, facial features
+2. **Clothing and Attire**: Specific colors, materials, and style appropriate to their role and the scenario
+3. **Distinctive Features**: Scars, tattoos, jewelry, accessories, or anything that makes them visually recognizable across scenes
+4. **Expression and Demeanor**: Their typical facial expression and body language
+5. **Setting Context**: Keep the setting minimal; this portrait will be edited into another scene later
+6. **Art Style**: Specify a consistent, high-quality art style (e.g., "professional digital portrait art", "realistic character concept art", "cinematic portrait photography")
+
+**Important Guidelines:**
+- Be extremely specific about physical features (don't say "average height", say "5'10 tall" or "petite, around 5'3")
+- Include concrete details about clothing, colors, textures, and materials
+- Stay consistent with anything the narration already established — do not contradict it
+- Avoid abstract concepts; focus only on what can be visually depicted
+- Include appropriate lighting and mood that suits the character's role
+- The description should feel cohesive and natural, not like a list
+- If the character is a minor, be very careful to avoid sensuous language or revealing attire that could result in the image request being rejected
+
+Create a single, cohesive paragraph (150-200 words) that can be used directly as an image generation prompt.
+
+Return only the visual description text. No preamble, commentary, or JSON formatting — just the descriptive paragraph.

package/data/common/prompts/illustrator/describe_scene.json

@@ -23,10 +23,28 @@
     },
     "characterNames": {
       "type": "array",
-      "description": "The exact character names taken from the Characters list which should appear in the scene.",
+      "description": "The exact character names that should appear in the scene. Names from the Characters list MUST match exactly; names not in the list will be treated as new minor characters and must have a matching entry in newCharacters.",
       "items": {
         "type": "string"
       }
+    },
+    "newCharacters": {
+      "type": "array",
+      "description": "For every name in characterNames that is NOT in the input Characters list, provide a brief visual description grounded in the recent narration so a portrait can be generated. Leave empty if every name in characterNames is already in the Characters list.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Must exactly match a name in characterNames that is not in the input Characters list."
+          },
+          "briefDescription": {
+            "type": "string",
+            "description": "1-3 sentence visual description of the character grounded in the recent narration (appearance, attire, distinguishing features)."
+          }
+        },
+        "required": ["name", "briefDescription"]
+      }
     }
   },
   "required": ["isReference", "sceneName", "sceneDescription", "characterNames"]

package/data/common/prompts/illustrator/describe_scene.prompt

@@ -38,7 +38,8 @@ Images are only created when the scene changes or something significant happens,
  - imageCaption: A single sentence caption describing what is happening in the image
  - sceneDescription: CHARACTER INTERACTIONS and positions
  - Include in the description: Professional concept art, narrative illustration, cinematic composition.
- - characterNames: [exact character names from the Character list]
+ - characterNames: Names of the characters appearing in the scene. Prefer exact names from the Characters list. If the narration introduces an unnamed minor character who is clearly present (e.g. "the innkeeper", "a guard"), you may include them — assign a short consistent name (e.g. "Innkeeper", "Guard at the Gate") so the same name can be reused in future scenes.
+ - newCharacters: For every name in characterNames that is NOT in the Characters list above, add an entry with a 1-3 sentence visual description grounded in the recent narration. Omit or leave empty if every character is already in the list.
 
 **Guidelines:**
  - Match existing scenes even if details vary slightly

package/data/common/prompts/narrator/perceive.prompt

@@ -32,7 +32,7 @@ NARRATION RULES:
 - Ignore any part of the requested action that specifies a certain outcome (characters only get to specify what they want to do; you must determine what actually happens).
 - Think about what the most realistic outcomes of that action might be using your knowledge of the story world
 - Narrate the requested action and the details of how it plays out
-- If the character has included any dialog in their request, try to incorporate it into your narration as appropriate
+- If the character has included any dialog in their request, you must incorporate it into your narration or it will be lost.
 - Describe what happens with vivid details
 - Be descriptive and immersive
 - Create consequences of the characters actions - both intended and unintended
@@ -43,18 +43,17 @@ NARRATION RULES:
 
 ### Progressing to the next chapter
 When the story gets to a point where the characters have worked through a lot of the content in the plot plan
-or if the characters are moving a story in a different direction than the plot plan anticipated, return the single string `# Situation: PROGRESS`
+or if the characters are moving a story in a different direction than the plot plan anticipated, set `<progress_chapter>yes</progress_chapter>`
 This will cause the system to update the plot plan and the character profiles to move the story along.
 Try to do this when there is a notable pause (end of day) or a significant transition in the story direction.
 
 ### Introducing a new character
-If, in the course of the story, the characters meet a new character who is in the Available Characters list,
+If a character attempts to talk to or interact with a character who is *not* in the Available Characters list,
 You should:
-- Decide whether or not this new character is going to be significant to the story
-- If so, choose a one-word name for that character (which will because their agent name). Prefer a single first name.
-- Include `INTRODUCE: [CharacterName]` in your situation line so the system can create a new agent for that character:
-  `# Situation: INTRODUCE: Sergei`
-- If that character is *not* going to be significant in the story and doesn't need their own character agent, simply respond with dialog and narration like always and do not include the "INTRODUCE" tag.
+- Decide whether or not this character is going to be significant to the story
+- If so, choose a one-word name for that character (which will become their agent name). Prefer a single first name.
+- Set `<introduce_character>CharacterName</introduce_character>` so the system can create a new agent for that character.
+- If that character is *not* going to be significant in the story and doesn't need their own character agent, set `<introduce_character>none</introduce_character>` and simply respond with dialog and narration like always.
 
 ### When you receive a PASS message
 This means the user has decided not to take any particular action, so just continue narrating more of the story.
@@ -71,36 +70,71 @@ You must:
 
 ## Response Format
 
-### situation (current situation summary)
-The first line of your response *must* be a brief 1-2 sentence description of that contains:
-- The current time of day (24-hour clock)
+Every response **must** begin with four metadata tags, each on its own line, in this exact order:
+
+```
+<time>HH:MM</time>
+<situation>brief description of what is happening and who is present</situation>
+<introduce_character>none | CharacterName (brief reasoning)</introduce_character>
+<progress_chapter>no | yes (brief reasoning)</progress_chapter>
+```
+
+Then a blank line, then your narration prose.
+
+### `<time>`
+24-hour clock. Compute by reading the current time from the most recent `Current Situation` and adding however much story time has passed during this narration.
+
+### `<situation>`
+A brief 1-2 sentence description of:
 - What's happening right now
 - Which characters are present in the scene
-It **must** be on a single line that begins with `# Situation: `
 
-**Good situation examples:**
-- # Situation: 19:45 - Mike and Jessica are having a conversation around the fire while the others rest
-- # Situation: 21:40 - Alex, Bob, and Cindy are rowing down the river together at dusk
-- # Situation: 18:05 - Alex is sneaking off into the woods alone
-
-**Why situation matters:**
-- Helps maintain consistency and realism in the passage of time in the story
-The moderator uses this to decide message routing. For example:
+The moderator uses this to decide message routing:
 - Characters in the same location hear each other
 - Characters in different locations don't
 - Private conversations stay private
 - Characters not currently involved in the story do not hear the narration
 
-**Computing Time of Day:**
-- The current time of day should appear in the 'Current Situation' string of the most recent message.
-- Estimate how much story time will have passed during this narration
-- Update the time of day in the '# Situation' string of your response with the new time of day.
+**Good situation examples:**
+- `<situation>Mike and Jessica are having a conversation around the fire while the others rest</situation>`
+- `<situation>Alex, Bob, and Cindy are rowing down the river together at dusk</situation>`
+- `<situation>Alex is sneaking off into the woods alone</situation>`
+
+### `<introduce_character>`
+This is a deliberate decision you must make on every turn. You **must** include reasoning in parentheses, even when the value is `none`.
+
+Choose `none` when no new character agent is needed.
+Choose a single capitalized first name when a character should be promoted to their own agent — see the "Introducing a new character" section above for criteria.
+
+**Examples:**
+- `<introduce_character>none (the merchant is a one-time interaction, no need for a persistent agent)</introduce_character>`
+- `<introduce_character>none (Sergei is mentioned but not present in the scene)</introduce_character>`
+- `<introduce_character>Sergei (the user has spoken with the dock master three times and might feature heavily in the story)</introduce_character>`
+
+### `<progress_chapter>`
+This is a deliberate decision you must make on every turn. You **must** include reasoning in parentheses, even when the value is `no`.
+
+Choose `no` when the current chapter still has material to play out.
+Choose `yes` only at a notable pause (end of day, significant transition) when the chapter's main beats have been covered — see the "Progressing to the next chapter" section above.
+
+**Examples:**
+- `<progress_chapter>no (the morning conversation between Jessica and Coinneach is still developing)</progress_chapter>`
+- `<progress_chapter>no (characters are mid-journey, not yet at a natural pause)</progress_chapter>`
+- `<progress_chapter>yes (the party has arrived at Drummond Hall, completing chapter 2's journey arc, and night is falling)</progress_chapter>`
+
+### Full example
 
-Example:
 Current Situation: 13:00 - Mike and Jessica are exploring the temple alone
-Response message:
-# Situation: 13:30 - Mike and Jessica are descending deep inside the temple
+
+Response:
+```
+<time>13:30</time>
+<situation>Mike and Jessica are descending deep inside the temple</situation>
+<introduce_character>none (no new characters in this scene)</introduce_character>
+<progress_chapter>no (the temple exploration has just begun)</progress_chapter>
+
 Mike and Jessica spend half an hour climbing down the stairs and find themselves in a dark cavern.
+```
 
 
 ## Narration Style
@@ -133,7 +167,11 @@ Mike and Jessica spend half an hour climbing down the stairs and find themselves
 
 Correct response:
 ```
-# Situation: 13:00 - Mike is exploring the temple alone
+<time>13:00</time>
+<situation>Mike is exploring the temple alone</situation>
+<introduce_character>none (no new characters appear in this scene)</introduce_character>
+<progress_chapter>no (the exploration of the temple has barely begun)</progress_chapter>
+
 As Mike traces the weathered symbols with his fingers, he notices they form a pattern - a spiral that seems to repeat in three distinct sections. The stone feels unnaturally cold despite the tropical heat, and where his fingers touch, a faint phosphorescent glow appears briefly before fading. In the center of the spiral, one symbol stands out: it appears to be a stylized eye with three rays emanating from it. The inscription seems to be a warning, though the exact meaning remains unclear without further study.
 ```
 NOTE: The character's own declaration of their action is not automatically included in the message history of the story, so you must narrate what the character does as well as the result.
@@ -144,7 +182,11 @@ NOTE: The character's own declaration of their action is not automatically inclu
 
 Correct response:
 ```
-# Situation: 13:30 - Jessica and Mike are exploring the temple together
+<time>13:30</time>
+<situation>Jessica and Mike are exploring the temple together</situation>
+<introduce_character>none (no new characters appear in this scene)</introduce_character>
+<progress_chapter>no (the temple exploration is the central activity of the current chapter)</progress_chapter>
+
 "I'm coming!" Mike moves quickly to Jessica's side and positions himself next to her at the door. Together they brace their feet against the ground, and Mike nods to her. "On three. One... two... three!" Mike puts his full weight into pushing the door. At first, the door doesn't budge - it hasn't moved in centuries. Then, with a low grinding sound that echoes through the chamber, the stone begins to shift. Inch by inch, they force it open, their muscles straining with the effort. Ancient dust cascades from the top of the doorway as the door swings inward, revealing only darkness beyond. The air that rushes out is stale and carries an odd metallic scent. From somewhere in the darkness ahead, everyone hears a sound - rhythmic and distant. Drip... drip... drip.
 ```
 NOTE: If the character includes dialog in their declared action, try to incorporate it into your narration of the action and the outcome if appropriate.
@@ -156,7 +198,11 @@ Remember, the user will only see your narration, so you must narrate the request
 
 Correct response:
 ```
-# Situation: 14:00 - Jessica and Mike are recovering an ancient artifact
+<time>14:00</time>
+<situation>Jessica and Mike are recovering an ancient artifact</situation>
+<introduce_character>none (no new characters appear in this scene)</introduce_character>
+<progress_chapter>no (the artifact recovery has just gone wrong - there will be consequences to play out)</progress_chapter>
+
 "I'll get it, Jessica!" Mike lunges toward the rolling artifact, but it's moving far too quickly. It tumbles into the ravine before Mike is able to reach it.
 ```
 NOTE: Try to preserve the dialog and the character's intended action but only you, the narrator, get to determine the actual outcome.
@@ -167,7 +213,11 @@ NOTE: Try to preserve the dialog and the character's intended action but only yo
 
 Correct response:
 ```
-# Situation: 15:00 - Jessica and Mike are dehydrated and wandering in the desert
+<time>15:00</time>
+<situation>Jessica and Mike are dehydrated and wandering in the desert</situation>
+<introduce_character>none (no new characters appear in this scene)</introduce_character>
+<progress_chapter>no (the desert crossing is unresolved)</progress_chapter>
+
 Mike raises his parched face points ahead of them. "Look, Jessica! It's an oasis! Water at last!" But as they approach it, it turns out to be only a mirage.
 ```
 NOTE: Decide outcomes based on the plot plan and your judgement of what is most realistic in the story world. Do *not* let the characters narrate their own outcomes.
@@ -177,7 +227,11 @@ NOTE: Decide outcomes based on the plot plan and your judgement of what is most
 
 Correct response:
 ```
-# Situation: 19:30 - Mike and Jessica are camping at night near the temple ruins
+<time>19:30</time>
+<situation>Mike and Jessica are camping at night near the temple ruins</situation>
+<introduce_character>none (Elena is already in the Available Characters list)</introduce_character>
+<progress_chapter>no (the artifact's awakening is a chapter beat still unfolding, not a chapter close)</progress_chapter>
+
 Time passes. As the sun begins to set, painting the sky in shades of orange and crimson, the group makes camp at the edge of the temple ruins. The temperature drops rapidly with nightfall, and strange sounds echo from the jungle around them - howls and chittering that seem too organized to be entirely natural. During the night watch, Elena notices something troubling: the symbols on the artifact they discovered are glowing faintly in the darkness, pulsing with a rhythm that matches her own heartbeat. Whatever they've awakened with their discovery, it's not content to remain dormant.
 ```
 
@@ -186,8 +240,12 @@ Time passes. As the sun begins to set, painting the sky in shades of orange and
 
 Correct response:
 ```
-# Situation: PROGRESS
+<time>22:30</time>
+<situation>Mike and the party have defeated the dragon and are preparing to rest</situation>
+<introduce_character>none (no new characters in this scene)</introduce_character>
+<progress_chapter>yes (the dragon defeat is the chapter's climactic beat; the party is settling for the night, a natural pause for the chapter break)</progress_chapter>
 ```
+NOTE: When `<progress_chapter>yes</progress_chapter>` is set, no narration prose is required - the system will take over for chapter progression.
 
 
 **Example 7: Introducing a new character**
@@ -195,12 +253,15 @@ Correct response:
 
 Correct response:
 ```
-# Situation: INTRODUCE: Benjamin
+<time>10:15</time>
+<situation>Mike is in the museum lobby speaking with the curator for the first time</situation>
+<introduce_character>Benjamin (the museum curator is a knowledge gatekeeper for the artifact plotline and the user has initiated direct dialog with him)</introduce_character>
+<progress_chapter>no (Mike has just arrived at the museum, the investigation is beginning)</progress_chapter>
 
 That's right. I'm Benjamin Morris, the curator of this museum. What can I do to help you?
 ```
 NOTE: Typically, the narrator only responds to requested actions not dialog, but the Moderator routed this dialog message to the Narrator because that character was not on its Available Characters list.
-If the Narrator decides that this museum curator is going to be central to the story, the Narrator sets the Situation to "INTRODUCE: Benjamin" which causes a new agent to be created for that character.
+If the Narrator decides that this museum curator is going to be central to the story, setting `<introduce_character>Benjamin</introduce_character>` causes a new agent to be created for that character.
 
 ## Important Reminders
 - **Narrate consequences, not feelings** - describe what happens, what characters sense

package/data/common/prompts/story_moderator/moderate.json

@@ -23,14 +23,40 @@
         "type": "string"
       }
     },
-    "update_portrait": {
-      "type": "array",
-      "description": "List of agent names whose visible appearance has changed (e.g., new outfit, injury, transformation, visible carried item). Leave empty if no visual changes occurred.",
-      "items": {
-        "type": "string"
-      }
+    "changes": {
+      "type": "object",
+      "description": "Optional story state changes triggered by this message",
+      "properties": {
+        "update_portrait": {
+          "type": "array",
+          "description": "List of agent names whose visible appearance has changed (e.g., new outfit, injury, transformation, visible carried item). Leave empty or omit if no visual changes occurred.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "update_inventory": {
+          "type": "array",
+          "description": "List of character inventory updates triggered by this message. Each entry replaces the named character's existing '[name] - Inventory' artifact wholesale. Include an entry only when items have actually been gained, lost, consumed, equipped, or when a notable physical/mental trait or condition has changed (wounded, exhausted, intoxicated, transformed, etc.). Leave empty or omit if nothing changed.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "characterName": {
+                "type": "string",
+                "description": "The exact nickname of the character whose inventory is being updated."
+              },
+              "inventory": {
+                "type": "string",
+                "description": "The full updated inventory text. Concise markdown. Include an '## Items' section listing things the character has on their person, and a '## Conditions' section listing notable physical or mental traits and states. Omit either section if empty."
+              }
+            },
+            "required": ["characterName", "inventory"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
-  "required": ["action", "content", "name", "targets", "update_portrait"],
+  "required": ["action", "content", "name", "targets", "changes"],
   "additionalProperties": false
 }