From 960536975064047ce6f11abc3b82ef3a636adfa9 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 05:00:20 -0500
Subject: [PATCH 01/24] feat: add ship receipts app shell

---
 .../main/apps/app_ship_receipts/README.md     | 39 ++++++++
 .../app_ship_receipts/app_ship_receipts.cpp   | 92 +++++++++++++++++++
 .../app_ship_receipts/app_ship_receipts.h     | 39 ++++++++
 firmware/main/apps/apps.h                     |  1 +
 firmware/main/main.cpp                        |  1 +
 5 files changed, 172 insertions(+)
 create mode 100644 firmware/main/apps/app_ship_receipts/README.md
 create mode 100644 firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
 create mode 100644 firmware/main/apps/app_ship_receipts/app_ship_receipts.h

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
new file mode 100644
index 00000000..54cce64c
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -0,0 +1,39 @@
+# Ship Receipts app shell
+
+This directory is the first explicit app boundary for integrating `ship-receipts`
+with StackChan.
+
+## Intent
+
+`ship-receipts` should be an **app on top of StackChan core**, not logic wired
+into generic firmware subsystems.
+
+That means:
+
+- keep **transport**, **motion**, **audio**, **diagnostics**, and **renderer
+  primitives** in StackChan core
+- keep **mode/content logic**, **copy**, **scene sequencing**, and
+  `ship-receipts` semantics in this app layer
+
+## Why this matters
+
+This split gives us:
+
+- a clean place to build host-driven game modes
+- better odds of upstreaming generic capabilities later
+- less pressure to turn StackChan core into a `ship-receipts`-specific product
+
+## What belongs here later
+
+- host scene packet consumers for Ship Receipts modes
+- Odyssey / Heike / future mode selection
+- app-local diagnostics relevant to Ship Receipts mode
+- branding and copy specific to this app
+
+## What should stay out
+
+- generic servo transport code
+- generic audio plumbing
+- generic small-screen layout helpers
+- generic packet logging / debugging
+
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
new file mode 100644
index 00000000..f6093f35
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -0,0 +1,92 @@
+/*
+ * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
+ *
+ * SPDX-License-Identifier: MIT
+ */
+#include "app_ship_receipts.h"
+#include <hal/hal.h>
+#include <mooncake_log.h>
+#include <smooth_lvgl.hpp>
+
+using namespace mooncake;
+using namespace smooth_ui_toolkit::lvgl_cpp;
+
+AppShipReceipts::AppShipReceipts()
+{
+    setAppInfo().name = "SHIP.RECEIPTS";
+
+    static uint32_t theme_color = 0x4A79E8;
+    setAppInfo().userData       = (void*)&theme_color;
+}
+
+void AppShipReceipts::onCreate()
+{
+    mclog::tagInfo(getAppInfo().name, "on create");
+}
+
+void AppShipReceipts::onOpen()
+{
+    mclog::tagInfo(getAppInfo().name, "on open");
+
+    LvglLockGuard lock;
+
+    _panel = std::make_unique<Container>(lv_screen_active());
+    _panel->setSize(320, 240);
+    _panel->setAlign(LV_ALIGN_CENTER);
+    _panel->setBorderWidth(0);
+    _panel->setRadius(0);
+    _panel->setPaddingAll(0);
+    _panel->setBgColor(lv_color_hex(0x0F172A));
+    _panel->setBgOpa(LV_OPA_100);
+
+    _title = std::make_unique<Label>(_panel->get());
+    _title->setText("SHIP RECEIPTS");
+    _title->setTextFont(&lv_font_montserrat_24);
+    _title->setTextColor(lv_color_hex(0xF8FAFC));
+    _title->align(LV_ALIGN_TOP_MID, 0, 20);
+
+    _subtitle = std::make_unique<Label>(_panel->get());
+    _subtitle->setText("App shell on top of StackChan core");
+    _subtitle->setTextFont(&lv_font_montserrat_14);
+    _subtitle->setTextColor(lv_color_hex(0x93C5FD));
+    _subtitle->alignTo(_title->get(), LV_ALIGN_OUT_BOTTOM_MID, 0, 8);
+
+    _body = std::make_unique<Label>(_panel->get());
+    _body->setWidth(268);
+    _body->setLongMode(LV_LABEL_LONG_WRAP);
+    _body->setText(
+        "This app boundary is where host-driven game modes belong.\n\n"
+        "- authored scene packets\n"
+        "- cards and avatar beats\n"
+        "- ship-receipts copy and rules\n\n"
+        "Keep transport, motion, audio, diagnostics, and render primitives in core.");
+    _body->setTextFont(&lv_font_montserrat_14);
+    _body->setTextColor(lv_color_hex(0xE2E8F0));
+    _body->align(LV_ALIGN_TOP_MID, 0, 82);
+
+    _button_quit = std::make_unique<Button>(_panel->get());
+    _button_quit->setSize(140, 42);
+    _button_quit->setBgColor(lv_color_hex(0x1D4ED8));
+    _button_quit->align(LV_ALIGN_BOTTOM_MID, 0, -18);
+    _button_quit->label().setText("BACK");
+    _button_quit->label().setTextColor(lv_color_hex(0xFFFFFF));
+    _button_quit->onClick().connect([this]() { close(); });
+}
+
+void AppShipReceipts::onRunning()
+{
+}
+
+void AppShipReceipts::onClose()
+{
+    mclog::tagInfo(getAppInfo().name, "on close");
+
+    LvglLockGuard lock;
+
+    _button_quit.reset();
+    _body.reset();
+    _subtitle.reset();
+    _title.reset();
+    _panel.reset();
+}
+
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
new file mode 100644
index 00000000..b34fbfb4
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -0,0 +1,39 @@
+/*
+ * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
+ *
+ * SPDX-License-Identifier: MIT
+ */
+#pragma once
+#include <mooncake.h>
+#include <memory>
+
+namespace smooth_ui_toolkit::lvgl_cpp {
+class Container;
+class Label;
+class Button;
+}
+
+/**
+ * @brief Ship Receipts app shell.
+ *
+ * This is intentionally a thin app boundary on top of StackChan core:
+ * generic device capabilities stay in core firmware, while Ship Receipts
+ * mode/content can evolve as an app.
+ */
+class AppShipReceipts : public mooncake::AppAbility {
+public:
+    AppShipReceipts();
+
+    void onCreate() override;
+    void onOpen() override;
+    void onRunning() override;
+    void onClose() override;
+
+private:
+    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Container> _panel;
+    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Label> _title;
+    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Label> _subtitle;
+    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Label> _body;
+    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Button> _button_quit;
+};
+
diff --git a/firmware/main/apps/apps.h b/firmware/main/apps/apps.h
index 77cc9b71..6ad92232 100644
--- a/firmware/main/apps/apps.h
+++ b/firmware/main/apps/apps.h
@@ -12,3 +12,4 @@
 #include "app_app_center/app_app_center.h"
 #include "app_ezdata/app_ezdata.h"
 #include "app_dance/app_dance.h"
+#include "app_ship_receipts/app_ship_receipts.h"
diff --git a/firmware/main/main.cpp b/firmware/main/main.cpp
index 164a7516..3ef0714a 100644
--- a/firmware/main/main.cpp
+++ b/firmware/main/main.cpp
@@ -34,6 +34,7 @@ extern "C" void app_main(void)
     GetMooncake().installApp(std::make_unique<AppAppCenter>());
     GetMooncake().installApp(std::make_unique<AppEzdata>());
     GetMooncake().installApp(std::make_unique<AppDance>());
+    GetMooncake().installApp(std::make_unique<AppShipReceipts>());
     GetMooncake().installApp(std::make_unique<AppSetup>());
 
     // Main loop

From 12f51b3305305e8d55a2d5dc98e5844aa46c4a73 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 05:06:44 -0500
Subject: [PATCH 02/24] refactor: align ship receipts shell with app model

---
 .../main/apps/app_ship_receipts/README.md     | 16 ++++
 .../app_ship_receipts/app_ship_receipts.cpp   | 86 ++++++++-----------
 .../app_ship_receipts/app_ship_receipts.h     | 15 +---
 3 files changed, 56 insertions(+), 61 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 54cce64c..ddd078a3 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -29,6 +29,11 @@ This split gives us:
 - Odyssey / Heike / future mode selection
 - app-local diagnostics relevant to Ship Receipts mode
 - branding and copy specific to this app
+- app-level use of generic core capabilities such as:
+  - avatar skin + speech
+  - motion updates
+  - audio cue playback
+  - transport-fed scene packets
 
 ## What should stay out
 
@@ -37,3 +42,14 @@ This split gives us:
 - generic small-screen layout helpers
 - generic packet logging / debugging
 
+## Current shell behavior
+
+The initial shell intentionally does very little:
+
+- opens as a normal StackChan app
+- attaches the default avatar
+- speaks an architecture reminder about app vs core boundaries
+- uses the standard home indicator and status bar
+
+This keeps the first seam tiny while still proving that `ship-receipts`
+can live as an app instead of a core firmware fork.
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index f6093f35..4c923a73 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -4,17 +4,23 @@
  * SPDX-License-Identifier: MIT
  */
 #include "app_ship_receipts.h"
+#include <apps/common/common.h>
+#include <assets/assets.h>
 #include <hal/hal.h>
 #include <mooncake_log.h>
+#include <stackchan/stackchan.h>
 #include <smooth_lvgl.hpp>
 
 using namespace mooncake;
-using namespace smooth_ui_toolkit::lvgl_cpp;
+using namespace stackchan;
 
 AppShipReceipts::AppShipReceipts()
 {
     setAppInfo().name = "SHIP.RECEIPTS";
 
+    static auto icon  = assets::get_image("icon_sentinel.bin");
+    setAppInfo().icon = (void*)&icon;
+
     static uint32_t theme_color = 0x4A79E8;
     setAppInfo().userData       = (void*)&theme_color;
 }
@@ -28,53 +34,39 @@ void AppShipReceipts::onOpen()
 {
     mclog::tagInfo(getAppInfo().name, "on open");
 
-    LvglLockGuard lock;
+    {
+        LvglLockGuard lock;
+
+        auto avatar = std::make_unique<avatar::DefaultAvatar>();
+        avatar->init(lv_screen_active());
+        GetStackChan().attachAvatar(std::move(avatar));
+
+        auto& stackchan = GetStackChan();
+        stackchan.avatar().setSpeech(
+            "Ship Receipts should live as an app. Keep motion, audio, and diagnostics in core.");
+        stackchan.addModifier(std::make_unique<TimedSpeechModifier>(
+            "Host-driven cards and avatar beats belong here.", 5000));
 
-    _panel = std::make_unique<Container>(lv_screen_active());
-    _panel->setSize(320, 240);
-    _panel->setAlign(LV_ALIGN_CENTER);
-    _panel->setBorderWidth(0);
-    _panel->setRadius(0);
-    _panel->setPaddingAll(0);
-    _panel->setBgColor(lv_color_hex(0x0F172A));
-    _panel->setBgOpa(LV_OPA_100);
-
-    _title = std::make_unique<Label>(_panel->get());
-    _title->setText("SHIP RECEIPTS");
-    _title->setTextFont(&lv_font_montserrat_24);
-    _title->setTextColor(lv_color_hex(0xF8FAFC));
-    _title->align(LV_ALIGN_TOP_MID, 0, 20);
-
-    _subtitle = std::make_unique<Label>(_panel->get());
-    _subtitle->setText("App shell on top of StackChan core");
-    _subtitle->setTextFont(&lv_font_montserrat_14);
-    _subtitle->setTextColor(lv_color_hex(0x93C5FD));
-    _subtitle->alignTo(_title->get(), LV_ALIGN_OUT_BOTTOM_MID, 0, 8);
-
-    _body = std::make_unique<Label>(_panel->get());
-    _body->setWidth(268);
-    _body->setLongMode(LV_LABEL_LONG_WRAP);
-    _body->setText(
-        "This app boundary is where host-driven game modes belong.\n\n"
-        "- authored scene packets\n"
-        "- cards and avatar beats\n"
-        "- ship-receipts copy and rules\n\n"
-        "Keep transport, motion, audio, diagnostics, and render primitives in core.");
-    _body->setTextFont(&lv_font_montserrat_14);
-    _body->setTextColor(lv_color_hex(0xE2E8F0));
-    _body->align(LV_ALIGN_TOP_MID, 0, 82);
-
-    _button_quit = std::make_unique<Button>(_panel->get());
-    _button_quit->setSize(140, 42);
-    _button_quit->setBgColor(lv_color_hex(0x1D4ED8));
-    _button_quit->align(LV_ALIGN_BOTTOM_MID, 0, -18);
-    _button_quit->label().setText("BACK");
-    _button_quit->label().setTextColor(lv_color_hex(0xFFFFFF));
-    _button_quit->onClick().connect([this]() { close(); });
+        view::create_home_indicator([&]() { close(); }, 0x93C5FD, 0x0F172A);
+        view::create_status_bar(0x93C5FD, 0x0F172A);
+        view::pop_a_toast("Ship Receipts app shell ready", view::ToastType::Info, 1800);
+    }
+
+    _open_tick = GetHAL().millis();
 }
 
 void AppShipReceipts::onRunning()
 {
+    LvglLockGuard lock;
+
+    GetStackChan().update();
+    view::update_home_indicator();
+    view::update_status_bar();
+
+    if (_open_tick > 0 && GetHAL().millis() - _open_tick > 6000) {
+        GetStackChan().avatar().setSpeech("");
+        _open_tick = 0;
+    }
 }
 
 void AppShipReceipts::onClose()
@@ -83,10 +75,8 @@ void AppShipReceipts::onClose()
 
     LvglLockGuard lock;
 
-    _button_quit.reset();
-    _body.reset();
-    _subtitle.reset();
-    _title.reset();
-    _panel.reset();
+    GetStackChan().resetAvatar();
+    view::destroy_home_indicator();
+    view::destroy_status_bar();
 }
 
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index b34fbfb4..f49481de 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -5,13 +5,7 @@
  */
 #pragma once
 #include <mooncake.h>
-#include <memory>
-
-namespace smooth_ui_toolkit::lvgl_cpp {
-class Container;
-class Label;
-class Button;
-}
+#include <cstdint>
 
 /**
  * @brief Ship Receipts app shell.
@@ -30,10 +24,5 @@ class AppShipReceipts : public mooncake::AppAbility {
     void onClose() override;
 
 private:
-    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Container> _panel;
-    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Label> _title;
-    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Label> _subtitle;
-    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Label> _body;
-    std::unique_ptr<smooth_ui_toolkit::lvgl_cpp::Button> _button_quit;
+    uint32_t _open_tick = 0;
 };
-

From 383cdfaf3689e76cd5bfef1997b8725e042661e9 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 05:14:11 -0500
Subject: [PATCH 03/24] feat: add ship receipts demo beats

---
 .../main/apps/app_ship_receipts/README.md     | 17 +++--
 .../app_ship_receipts/app_ship_receipts.cpp   | 62 +++++++++++++++----
 .../app_ship_receipts/app_ship_receipts.h     | 33 +++++++++-
 3 files changed, 96 insertions(+), 16 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index ddd078a3..2e709824 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -44,12 +44,21 @@ This split gives us:
 
 ## Current shell behavior
 
-The initial shell intentionally does very little:
+The current shell is still intentionally small, but it now demonstrates an
+app-local "director" loop that uses generic StackChan core capabilities:
 
 - opens as a normal StackChan app
 - attaches the default avatar
-- speaks an architecture reminder about app vs core boundaries
+- rotates through a few Ship Receipts sample beats
+- uses:
+  - status text for the beat label
+  - avatar speech for the beat line
+  - built-in emotions for expression
+  - head motion for staging
+  - RGB color changes for mood
+  - built-in notification audio for cueing
 - uses the standard home indicator and status bar
 
-This keeps the first seam tiny while still proving that `ship-receipts`
-can live as an app instead of a core firmware fork.
+This keeps the seam app-local while proving a stronger point than the original
+stub: Ship Receipts can direct StackChan through existing core APIs without
+turning the core firmware into a Ship Receipts-specific fork.
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 4c923a73..957c05db 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -6,7 +6,10 @@
 #include "app_ship_receipts.h"
 #include <apps/common/common.h>
 #include <assets/assets.h>
+#include <board.h>
+#include <display.h>
 #include <hal/hal.h>
+#include <hal/board/hal_bridge.h>
 #include <mooncake_log.h>
 #include <stackchan/stackchan.h>
 #include <smooth_lvgl.hpp>
@@ -41,18 +44,13 @@ void AppShipReceipts::onOpen()
         avatar->init(lv_screen_active());
         GetStackChan().attachAvatar(std::move(avatar));
 
-        auto& stackchan = GetStackChan();
-        stackchan.avatar().setSpeech(
-            "Ship Receipts should live as an app. Keep motion, audio, and diagnostics in core.");
-        stackchan.addModifier(std::make_unique<TimedSpeechModifier>(
-            "Host-driven cards and avatar beats belong here.", 5000));
-
         view::create_home_indicator([&]() { close(); }, 0x93C5FD, 0x0F172A);
         view::create_status_bar(0x93C5FD, 0x0F172A);
-        view::pop_a_toast("Ship Receipts app shell ready", view::ToastType::Info, 1800);
     }
 
-    _open_tick = GetHAL().millis();
+    _beat_index = 0;
+    applyBeat(_beats[_beat_index]);
+    view::pop_a_toast("Ship Receipts demo shell ready", view::ToastType::Info, 1800);
 }
 
 void AppShipReceipts::onRunning()
@@ -63,9 +61,11 @@ void AppShipReceipts::onRunning()
     view::update_home_indicator();
     view::update_status_bar();
 
-    if (_open_tick > 0 && GetHAL().millis() - _open_tick > 6000) {
-        GetStackChan().avatar().setSpeech("");
-        _open_tick = 0;
+    if (_beat_started_at > 0) {
+        const auto& beat = _beats[_beat_index];
+        if (GetHAL().millis() - _beat_started_at >= beat.duration_ms) {
+            advanceBeat();
+        }
     }
 }
 
@@ -75,8 +75,48 @@ void AppShipReceipts::onClose()
 
     LvglLockGuard lock;
 
+    clearBeat();
     GetStackChan().resetAvatar();
     view::destroy_home_indicator();
     view::destroy_status_bar();
 }
 
+void AppShipReceipts::applyBeat(const Beat& beat)
+{
+    auto* display = Board::GetInstance().GetDisplay();
+    auto& stack   = GetStackChan();
+    auto& motion  = stack.motion();
+
+    if (display) {
+        display->SetStatus(beat.title.data());
+        display->SetEmotion(beat.emotion.data());
+        display->SetChatMessage("assistant", beat.line.data());
+        display->ShowNotification(beat.title.data(), 1400);
+    }
+
+    if (beat.play_notification) {
+        hal_bridge::app_play_sound(OGG_NEW_NOTIFICATION);
+    }
+
+    GetHAL().showRgbColor(beat.led_r, beat.led_g, beat.led_b);
+    motion.moveWithSpeed(beat.yaw_angle, beat.pitch_angle, beat.speed);
+    _beat_started_at = GetHAL().millis();
+}
+
+void AppShipReceipts::clearBeat()
+{
+    if (auto* display = Board::GetInstance().GetDisplay()) {
+        display->ClearChatMessages();
+        display->SetStatus("");
+    }
+
+    GetHAL().showRgbColor(0, 0, 0);
+    GetStackChan().motion().goHome(320);
+    _beat_started_at = 0;
+}
+
+void AppShipReceipts::advanceBeat()
+{
+    _beat_index = (_beat_index + 1) % _beats.size();
+    applyBeat(_beats[_beat_index]);
+}
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index f49481de..f66862b1 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -6,6 +6,8 @@
 #pragma once
 #include <mooncake.h>
 #include <cstdint>
+#include <array>
+#include <string_view>
 
 /**
  * @brief Ship Receipts app shell.
@@ -24,5 +26,34 @@ class AppShipReceipts : public mooncake::AppAbility {
     void onClose() override;
 
 private:
-    uint32_t _open_tick = 0;
+    struct Beat {
+        std::string_view title;
+        std::string_view line;
+        std::string_view emotion;
+        uint32_t duration_ms;
+        int yaw_angle;
+        int pitch_angle;
+        int speed;
+        uint8_t led_r;
+        uint8_t led_g;
+        uint8_t led_b;
+        bool play_notification;
+    };
+
+    static constexpr std::array<Beat, 4> _beats{{
+        {"SHIP.RECEIPTS", "Host-driven scenes belong in the app layer.", "neutral", 3600, 0, 0, 420, 0, 0, 0,
+         false},
+        {"HEIKE", "Bell sounds. All things impermanent.", "sad", 4200, 180, 170, 320, 64, 40, 0, true},
+        {"ODYSSEY", "A card beat can become status plus speech.", "happy", 3600, -220, 110, 320, 0, 40, 72,
+         false},
+        {"APP BOUNDARY", "Motion, LEDs, and audio cues stay generic.", "doubtful", 4200, 0, 40, 260, 36, 0, 56,
+         true},
+    }};
+
+    void applyBeat(const Beat& beat);
+    void clearBeat();
+    void advanceBeat();
+
+    uint32_t _beat_started_at = 0;
+    size_t _beat_index        = 0;
 };

From b29c2798332d9c36531ace52c6724ad19ecded88 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 05:17:37 -0500
Subject: [PATCH 04/24] feat: add ship receipts scene parser

---
 .../main/apps/app_ship_receipts/README.md     | 15 ++-
 .../app_ship_receipts/app_ship_receipts.cpp   | 34 +++++--
 .../app_ship_receipts/app_ship_receipts.h     | 35 ++-----
 .../app_ship_receipts/ship_receipts_scene.cpp | 92 +++++++++++++++++++
 .../app_ship_receipts/ship_receipts_scene.h   | 28 ++++++
 5 files changed, 168 insertions(+), 36 deletions(-)
 create mode 100644 firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
 create mode 100644 firmware/main/apps/app_ship_receipts/ship_receipts_scene.h

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 2e709824..4ab35bf5 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -45,7 +45,10 @@ This split gives us:
 ## Current shell behavior
 
 The current shell is still intentionally small, but it now demonstrates an
-app-local "director" loop that uses generic StackChan core capabilities:
+app-local "director" loop backed by a tiny scene payload parser.
+
+Each sample beat is authored as app-local JSON and then mapped onto generic
+StackChan primitives.
 
 - opens as a normal StackChan app
 - attaches the default avatar
@@ -62,3 +65,13 @@ app-local "director" loop that uses generic StackChan core capabilities:
 This keeps the seam app-local while proving a stronger point than the original
 stub: Ship Receipts can direct StackChan through existing core APIs without
 turning the core firmware into a Ship Receipts-specific fork.
+
+## Why the tiny parser matters
+
+The new parser is intentionally app-local:
+
+- it lets us evolve Ship Receipts scene semantics without changing StackChan
+  core first
+- it gives us a clean place to experiment with app-specific scene packets
+- it creates an extraction seam later if some subset becomes generic enough to
+  upstream
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 957c05db..e9ba1970 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -49,7 +49,9 @@ void AppShipReceipts::onOpen()
     }
 
     _beat_index = 0;
-    applyBeat(_beats[_beat_index]);
+    if (loadScene(_beat_index, _active_scene)) {
+        applyBeat(_active_scene);
+    }
     view::pop_a_toast("Ship Receipts demo shell ready", view::ToastType::Info, 1800);
 }
 
@@ -62,8 +64,7 @@ void AppShipReceipts::onRunning()
     view::update_status_bar();
 
     if (_beat_started_at > 0) {
-        const auto& beat = _beats[_beat_index];
-        if (GetHAL().millis() - _beat_started_at >= beat.duration_ms) {
+        if (GetHAL().millis() - _beat_started_at >= _active_scene.duration_ms) {
             advanceBeat();
         }
     }
@@ -81,17 +82,28 @@ void AppShipReceipts::onClose()
     view::destroy_status_bar();
 }
 
-void AppShipReceipts::applyBeat(const Beat& beat)
+bool AppShipReceipts::loadScene(size_t index, ship_receipts::ScenePayload& out_scene)
+{
+    std::string error_message;
+    if (!ship_receipts::parse_scene_payload(_scene_json[index], out_scene, &error_message)) {
+        mclog::tagError(getAppInfo().name, "failed to parse scene %u: %s", static_cast<unsigned>(index),
+                        error_message.c_str());
+        return false;
+    }
+    return true;
+}
+
+void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
 {
     auto* display = Board::GetInstance().GetDisplay();
     auto& stack   = GetStackChan();
     auto& motion  = stack.motion();
 
     if (display) {
-        display->SetStatus(beat.title.data());
-        display->SetEmotion(beat.emotion.data());
-        display->SetChatMessage("assistant", beat.line.data());
-        display->ShowNotification(beat.title.data(), 1400);
+        display->SetStatus(beat.title.c_str());
+        display->SetEmotion(beat.emotion.c_str());
+        display->SetChatMessage("assistant", beat.line.c_str());
+        display->ShowNotification(beat.title.c_str(), 1400);
     }
 
     if (beat.play_notification) {
@@ -117,6 +129,8 @@ void AppShipReceipts::clearBeat()
 
 void AppShipReceipts::advanceBeat()
 {
-    _beat_index = (_beat_index + 1) % _beats.size();
-    applyBeat(_beats[_beat_index]);
+    _beat_index = (_beat_index + 1) % _scene_json.size();
+    if (loadScene(_beat_index, _active_scene)) {
+        applyBeat(_active_scene);
+    }
 }
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index f66862b1..64b3173d 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -4,10 +4,10 @@
  * SPDX-License-Identifier: MIT
  */
 #pragma once
+#include "ship_receipts_scene.h"
 #include <mooncake.h>
-#include <cstdint>
 #include <array>
-#include <string_view>
+#include <cstdint>
 
 /**
  * @brief Ship Receipts app shell.
@@ -26,34 +26,19 @@ class AppShipReceipts : public mooncake::AppAbility {
     void onClose() override;
 
 private:
-    struct Beat {
-        std::string_view title;
-        std::string_view line;
-        std::string_view emotion;
-        uint32_t duration_ms;
-        int yaw_angle;
-        int pitch_angle;
-        int speed;
-        uint8_t led_r;
-        uint8_t led_g;
-        uint8_t led_b;
-        bool play_notification;
-    };
-
-    static constexpr std::array<Beat, 4> _beats{{
-        {"SHIP.RECEIPTS", "Host-driven scenes belong in the app layer.", "neutral", 3600, 0, 0, 420, 0, 0, 0,
-         false},
-        {"HEIKE", "Bell sounds. All things impermanent.", "sad", 4200, 180, 170, 320, 64, 40, 0, true},
-        {"ODYSSEY", "A card beat can become status plus speech.", "happy", 3600, -220, 110, 320, 0, 40, 72,
-         false},
-        {"APP BOUNDARY", "Motion, LEDs, and audio cues stay generic.", "doubtful", 4200, 0, 40, 260, 36, 0, 56,
-         true},
+    static constexpr std::array<const char*, 4> _scene_json{{
+        R"json({"title":"SHIP.RECEIPTS","line":"Host-driven scenes belong in the app layer.","emotion":"neutral","duration_ms":3600,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":0,"b":0},"play_notification":false})json",
+        R"json({"title":"HEIKE","line":"Bell sounds. All things impermanent.","emotion":"sad","duration_ms":4200,"motion":{"yaw_angle":180,"pitch_angle":170,"speed":320},"led":{"r":64,"g":40,"b":0},"play_notification":true})json",
+        R"json({"title":"ODYSSEY","line":"A card beat can become status plus speech.","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":72},"play_notification":false})json",
+        R"json({"title":"APP BOUNDARY","line":"Motion, LEDs, and audio cues stay generic.","emotion":"doubtful","duration_ms":4200,"motion":{"yaw_angle":0,"pitch_angle":40,"speed":260},"led":{"r":36,"g":0,"b":56},"play_notification":true})json",
     }};
 
-    void applyBeat(const Beat& beat);
+    bool loadScene(size_t index, ship_receipts::ScenePayload& out_scene);
+    void applyBeat(const ship_receipts::ScenePayload& beat);
     void clearBeat();
     void advanceBeat();
 
     uint32_t _beat_started_at = 0;
     size_t _beat_index        = 0;
+    ship_receipts::ScenePayload _active_scene{};
 };
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
new file mode 100644
index 00000000..aeb8078f
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
@@ -0,0 +1,92 @@
+/*
+ * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
+ *
+ * SPDX-License-Identifier: MIT
+ */
+#include "ship_receipts_scene.h"
+#include <ArduinoJson.hpp>
+
+namespace ship_receipts {
+
+namespace {
+
+void set_error(std::string* error_message, const char* message)
+{
+    if (error_message) {
+        *error_message = message;
+    }
+}
+
+uint8_t clamp_color(int value)
+{
+    if (value < 0) {
+        return 0;
+    }
+    if (value > 255) {
+        return 255;
+    }
+    return static_cast<uint8_t>(value);
+}
+
+}  // namespace
+
+bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::string* error_message)
+{
+    if (!json) {
+        set_error(error_message, "scene payload was null");
+        return false;
+    }
+
+    ArduinoJson::JsonDocument doc;
+    auto error = ArduinoJson::deserializeJson(doc, json);
+    if (error) {
+        set_error(error_message, error.c_str());
+        return false;
+    }
+
+    if (doc["title"].is<const char*>()) {
+        out_payload.title = doc["title"].as<const char*>();
+    }
+    if (doc["line"].is<const char*>()) {
+        out_payload.line = doc["line"].as<const char*>();
+    }
+    if (doc["emotion"].is<const char*>()) {
+        out_payload.emotion = doc["emotion"].as<const char*>();
+    }
+    if (doc["duration_ms"].is<uint32_t>()) {
+        out_payload.duration_ms = doc["duration_ms"].as<uint32_t>();
+    }
+    if (doc["play_notification"].is<bool>()) {
+        out_payload.play_notification = doc["play_notification"].as<bool>();
+    }
+
+    if (doc["motion"].is<ArduinoJson::JsonObject>()) {
+        auto motion = doc["motion"].as<ArduinoJson::JsonObject>();
+        if (motion["yaw_angle"].is<int>()) {
+            out_payload.yaw_angle = motion["yaw_angle"].as<int>();
+        }
+        if (motion["pitch_angle"].is<int>()) {
+            out_payload.pitch_angle = motion["pitch_angle"].as<int>();
+        }
+        if (motion["speed"].is<int>()) {
+            out_payload.speed = motion["speed"].as<int>();
+        }
+    }
+
+    if (doc["led"].is<ArduinoJson::JsonObject>()) {
+        auto led = doc["led"].as<ArduinoJson::JsonObject>();
+        if (led["r"].is<int>()) {
+            out_payload.led_r = clamp_color(led["r"].as<int>());
+        }
+        if (led["g"].is<int>()) {
+            out_payload.led_g = clamp_color(led["g"].as<int>());
+        }
+        if (led["b"].is<int>()) {
+            out_payload.led_b = clamp_color(led["b"].as<int>());
+        }
+    }
+
+    return true;
+}
+
+}  // namespace ship_receipts
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
new file mode 100644
index 00000000..d34fa408
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
@@ -0,0 +1,28 @@
+/*
+ * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
+ *
+ * SPDX-License-Identifier: MIT
+ */
+#pragma once
+#include <cstdint>
+#include <string>
+
+namespace ship_receipts {
+
+struct ScenePayload {
+    std::string title        = "SHIP.RECEIPTS";
+    std::string line         = "";
+    std::string emotion      = "neutral";
+    uint32_t duration_ms     = 3600;
+    int yaw_angle            = 0;
+    int pitch_angle          = 0;
+    int speed                = 320;
+    uint8_t led_r            = 0;
+    uint8_t led_g            = 0;
+    uint8_t led_b            = 0;
+    bool play_notification   = false;
+};
+
+bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::string* error_message = nullptr);
+
+}  // namespace ship_receipts

From 1391eab7da00af9730d7a47e983dffaa49a79ce1 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 05:24:16 -0500
Subject: [PATCH 05/24] feat: add ship receipts scene ingest hooks

---
 .../main/apps/app_ship_receipts/README.md     | 31 +++++++++
 .../app_ship_receipts/app_ship_receipts.cpp   | 65 +++++++++++++++++++
 .../app_ship_receipts/app_ship_receipts.h     |  8 +++
 .../app_ship_receipts/ship_receipts_scene.cpp | 28 ++++++++
 .../app_ship_receipts/ship_receipts_scene.h   |  1 +
 5 files changed, 133 insertions(+)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 4ab35bf5..0724bf1c 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -75,3 +75,34 @@ The new parser is intentionally app-local:
 - it gives us a clean place to experiment with app-specific scene packets
 - it creates an extraction seam later if some subset becomes generic enough to
   upstream
+
+## Current ingest paths
+
+The app now accepts app-local scene payloads through existing transport
+surfaces, without inventing a Ship Receipts-specific core protocol first:
+
+- BLE config writes
+- websocket text messages from the `ship-receipts` sender name
+
+Accepted shapes:
+
+- a raw scene object
+- or a command envelope:
+
+```json
+{
+  "cmd": "shipReceiptsScene",
+  "data": {
+    "title": "HEIKE",
+    "line": "Bell sounds. All things impermanent.",
+    "emotion": "sad",
+    "duration_ms": 4200,
+    "motion": {"yaw_angle": 180, "pitch_angle": 170, "speed": 320},
+    "led": {"r": 64, "g": 40, "b": 0},
+    "play_notification": true
+  }
+}
+```
+
+This keeps the transport generic while letting the Ship Receipts app own its
+scene semantics.
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index e9ba1970..7514394b 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -13,6 +13,7 @@
 #include <mooncake_log.h>
 #include <stackchan/stackchan.h>
 #include <smooth_lvgl.hpp>
+#include <string_view>
 
 using namespace mooncake;
 using namespace stackchan;
@@ -37,8 +38,22 @@ void AppShipReceipts::onOpen()
 {
     mclog::tagInfo(getAppInfo().name, "on open");
 
+    std::unique_ptr<view::LoadingPage> loading_page;
     {
         LvglLockGuard lock;
+        loading_page = std::make_unique<view::LoadingPage>(0x93C5FD, 0x0F172A);
+        loading_page->setMessage("Starting\n scene services...");
+    }
+
+    GetHAL().startBleServer();
+    GetHAL().startWebSocketAvatarService([&](std::string_view msg) {
+        LvglLockGuard lock;
+        loading_page->setMessage(msg);
+    });
+
+    {
+        LvglLockGuard lock;
+        loading_page.reset();
 
         auto avatar = std::make_unique<avatar::DefaultAvatar>();
         avatar->init(lv_screen_active());
@@ -48,6 +63,13 @@ void AppShipReceipts::onOpen()
         view::create_status_bar(0x93C5FD, 0x0F172A);
     }
 
+    GetHAL().onBleConfigData.connect([&](const char* data) { enqueueSceneJson(data ? data : ""); });
+    GetHAL().onWsTextMessage.connect([&](const WsTextMessage_t& message) {
+        if (message.name == "ship-receipts") {
+            enqueueSceneJson(message.content);
+        }
+    });
+
     _beat_index = 0;
     if (loadScene(_beat_index, _active_scene)) {
         applyBeat(_active_scene);
@@ -59,6 +81,11 @@ void AppShipReceipts::onRunning()
 {
     LvglLockGuard lock;
 
+    std::string queued_scene;
+    if (dequeueSceneJson(queued_scene)) {
+        applyQueuedSceneJson(queued_scene);
+    }
+
     GetStackChan().update();
     view::update_home_indicator();
     view::update_status_bar();
@@ -78,8 +105,12 @@ void AppShipReceipts::onClose()
 
     clearBeat();
     GetStackChan().resetAvatar();
+    GetHAL().onBleConfigData.clear();
+    GetHAL().onWsTextMessage.clear();
     view::destroy_home_indicator();
     view::destroy_status_bar();
+
+    GetHAL().requestWarmReboot(1);
 }
 
 bool AppShipReceipts::loadScene(size_t index, ship_receipts::ScenePayload& out_scene)
@@ -115,6 +146,38 @@ void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
     _beat_started_at = GetHAL().millis();
 }
 
+void AppShipReceipts::enqueueSceneJson(std::string json)
+{
+    std::lock_guard<std::mutex> lock(_queue_mutex);
+    _pending_scene_json.push_back(std::move(json));
+}
+
+bool AppShipReceipts::dequeueSceneJson(std::string& out_json)
+{
+    std::lock_guard<std::mutex> lock(_queue_mutex);
+    if (_pending_scene_json.empty()) {
+        return false;
+    }
+    out_json = std::move(_pending_scene_json.front());
+    _pending_scene_json.pop_front();
+    return true;
+}
+
+void AppShipReceipts::applyQueuedSceneJson(const std::string& json)
+{
+    ship_receipts::ScenePayload parsed;
+    std::string error_message;
+    if (!ship_receipts::parse_scene_command(json.c_str(), parsed, &error_message)) {
+        mclog::tagError(getAppInfo().name, "failed to parse incoming scene: %s", error_message.c_str());
+        view::pop_a_toast("Ship Receipts scene parse failed", view::ToastType::Error, 2200);
+        return;
+    }
+
+    _active_scene = std::move(parsed);
+    applyBeat(_active_scene);
+    view::pop_a_toast("Ship Receipts scene received", view::ToastType::Info, 1200);
+}
+
 void AppShipReceipts::clearBeat()
 {
     if (auto* display = Board::GetInstance().GetDisplay()) {
@@ -125,6 +188,8 @@ void AppShipReceipts::clearBeat()
     GetHAL().showRgbColor(0, 0, 0);
     GetStackChan().motion().goHome(320);
     _beat_started_at = 0;
+    std::lock_guard<std::mutex> lock(_queue_mutex);
+    _pending_scene_json.clear();
 }
 
 void AppShipReceipts::advanceBeat()
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index 64b3173d..ac80bda0 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -8,6 +8,9 @@
 #include <mooncake.h>
 #include <array>
 #include <cstdint>
+#include <deque>
+#include <mutex>
+#include <string>
 
 /**
  * @brief Ship Receipts app shell.
@@ -34,10 +37,15 @@ class AppShipReceipts : public mooncake::AppAbility {
     }};
 
     bool loadScene(size_t index, ship_receipts::ScenePayload& out_scene);
+    void enqueueSceneJson(std::string json);
+    bool dequeueSceneJson(std::string& out_json);
+    void applyQueuedSceneJson(const std::string& json);
     void applyBeat(const ship_receipts::ScenePayload& beat);
     void clearBeat();
     void advanceBeat();
 
+    std::mutex _queue_mutex;
+    std::deque<std::string> _pending_scene_json;
     uint32_t _beat_started_at = 0;
     size_t _beat_index        = 0;
     ship_receipts::ScenePayload _active_scene{};
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
index aeb8078f..fe90cc6a 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
@@ -89,4 +89,32 @@ bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::strin
     return true;
 }
 
+bool parse_scene_command(const char* json, ScenePayload& out_payload, std::string* error_message)
+{
+    if (!json) {
+        set_error(error_message, "scene command was null");
+        return false;
+    }
+
+    ArduinoJson::JsonDocument doc;
+    auto error = ArduinoJson::deserializeJson(doc, json);
+    if (error) {
+        set_error(error_message, error.c_str());
+        return false;
+    }
+
+    if (doc["cmd"].is<const char*>() && std::string_view(doc["cmd"].as<const char*>()) == "shipReceiptsScene") {
+        if (!doc["data"].is<ArduinoJson::JsonObject>()) {
+            set_error(error_message, "shipReceiptsScene command missing object data");
+            return false;
+        }
+
+        std::string nested;
+        ArduinoJson::serializeJson(doc["data"], nested);
+        return parse_scene_payload(nested.c_str(), out_payload, error_message);
+    }
+
+    return parse_scene_payload(json, out_payload, error_message);
+}
+
 }  // namespace ship_receipts
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
index d34fa408..7cbadbde 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
@@ -24,5 +24,6 @@ struct ScenePayload {
 };
 
 bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::string* error_message = nullptr);
+bool parse_scene_command(const char* json, ScenePayload& out_payload, std::string* error_message = nullptr);
 
 }  // namespace ship_receipts

From 37034e20c3c60503c28ed193e9c0501d289809e5 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 05:27:19 -0500
Subject: [PATCH 06/24] docs: add ship receipts scene examples

---
 .../main/apps/app_ship_receipts/README.md     | 24 ++++++++++
 .../examples/heike_scene.json                 | 17 +++++++
 .../examples/odyssey_scene.json               | 17 +++++++
 .../examples/ship_receipts_scene_command.json | 20 +++++++++
 .../tools/emit_ship_receipts_scene.py         | 44 +++++++++++++++++++
 5 files changed, 122 insertions(+)
 create mode 100644 firmware/main/apps/app_ship_receipts/examples/heike_scene.json
 create mode 100644 firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
 create mode 100644 firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
 create mode 100755 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 0724bf1c..91393b01 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -106,3 +106,27 @@ Accepted shapes:
 
 This keeps the transport generic while letting the Ship Receipts app own its
 scene semantics.
+
+## Example payloads and host helper
+
+Checked-in examples live here:
+
+- [examples/heike_scene.json](./examples/heike_scene.json)
+- [examples/odyssey_scene.json](./examples/odyssey_scene.json)
+- [examples/ship_receipts_scene_command.json](./examples/ship_receipts_scene_command.json)
+
+A tiny helper can emit the supported payload shapes without adding any new
+dependencies:
+
+- [tools/emit_ship_receipts_scene.py](./tools/emit_ship_receipts_scene.py)
+
+Examples:
+
+```bash
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format scene
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format command
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format ws-text
+```
+
+The `ws-text` format emits the `name` + `content` shape expected by the app's
+websocket text-message ingest path.
diff --git a/firmware/main/apps/app_ship_receipts/examples/heike_scene.json b/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
new file mode 100644
index 00000000..83ebf30e
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
@@ -0,0 +1,17 @@
+{
+  "title": "HEIKE",
+  "line": "Bell sounds. All things impermanent.",
+  "emotion": "sad",
+  "duration_ms": 4200,
+  "motion": {
+    "yaw_angle": 180,
+    "pitch_angle": 170,
+    "speed": 320
+  },
+  "led": {
+    "r": 64,
+    "g": 40,
+    "b": 0
+  },
+  "play_notification": true
+}
diff --git a/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json b/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
new file mode 100644
index 00000000..2c4290c3
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
@@ -0,0 +1,17 @@
+{
+  "title": "ODYSSEY",
+  "line": "A card beat can become status plus speech.",
+  "emotion": "happy",
+  "duration_ms": 3600,
+  "motion": {
+    "yaw_angle": -220,
+    "pitch_angle": 110,
+    "speed": 320
+  },
+  "led": {
+    "r": 0,
+    "g": 40,
+    "b": 72
+  },
+  "play_notification": false
+}
diff --git a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
new file mode 100644
index 00000000..91cee46c
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
@@ -0,0 +1,20 @@
+{
+  "cmd": "shipReceiptsScene",
+  "data": {
+    "title": "HEIKE",
+    "line": "Bell sounds. All things impermanent.",
+    "emotion": "sad",
+    "duration_ms": 4200,
+    "motion": {
+      "yaw_angle": 180,
+      "pitch_angle": 170,
+      "speed": 320
+    },
+    "led": {
+      "r": 64,
+      "g": 40,
+      "b": 0
+    },
+    "play_notification": true
+  }
+}
diff --git a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
new file mode 100755
index 00000000..ca7e67ba
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+import argparse
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+EXAMPLES = ROOT / "examples"
+
+SCENES = {
+    "heike": EXAMPLES / "heike_scene.json",
+    "odyssey": EXAMPLES / "odyssey_scene.json",
+}
+
+
+def load_scene(name: str) -> dict:
+    return json.loads(SCENES[name].read_text())
+
+
+def build_output(scene: dict, fmt: str) -> dict:
+    if fmt == "scene":
+        return scene
+    if fmt == "command":
+        return {"cmd": "shipReceiptsScene", "data": scene}
+    if fmt == "ws-text":
+        return {
+            "name": "ship-receipts",
+            "content": json.dumps({"cmd": "shipReceiptsScene", "data": scene}, ensure_ascii=False),
+        }
+    raise ValueError(f"unknown format: {fmt}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Emit Ship Receipts app scene payloads for StackChan")
+    parser.add_argument("--scene", choices=sorted(SCENES.keys()), default="heike")
+    parser.add_argument("--format", choices=["scene", "command", "ws-text"], default="command")
+    args = parser.parse_args()
+
+    scene = load_scene(args.scene)
+    payload = build_output(scene, args.format)
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

From 46c1c541f41658b46c889d9826cecc2bfa54cd4d Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 06:11:13 -0500
Subject: [PATCH 07/24] feat: support card and avatar scene beats

---
 .../main/apps/app_ship_receipts/README.md     | 24 +++++++++++++++
 .../app_ship_receipts/app_ship_receipts.cpp   | 30 +++++++++++++++++--
 .../app_ship_receipts/app_ship_receipts.h     |  8 ++---
 .../examples/heike_scene.json                 |  3 ++
 .../examples/odyssey_scene.json               |  2 ++
 .../examples/ship_receipts_scene_command.json |  3 ++
 .../app_ship_receipts/ship_receipts_scene.cpp |  9 ++++++
 .../app_ship_receipts/ship_receipts_scene.h   | 25 +++++++++-------
 8 files changed, 87 insertions(+), 17 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 91393b01..f19518c3 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -107,6 +107,30 @@ Accepted shapes:
 This keeps the transport generic while letting the Ship Receipts app own its
 scene semantics.
 
+## Current scene fields
+
+The app-local scene payload currently understands:
+
+- `title`
+- `line`
+- `speaker` (optional)
+- `presentation_type` (`card` or `avatar`)
+- `visual_template` (currently metadata, preserved for future renderer choices)
+- `emotion`
+- `duration_ms`
+- `motion`
+- `led`
+- `play_notification`
+
+Current rendering behavior:
+
+- `presentation_type = "avatar"`
+  - keeps the authored emotion
+  - prefixes speech with `speaker says:` when a speaker is present
+- `presentation_type = "card"`
+  - forces a neutral face
+  - treats speech as supporting card copy instead of character dialogue
+
 ## Example payloads and host helper
 
 Checked-in examples live here:
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 7514394b..03351223 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -18,6 +18,31 @@
 using namespace mooncake;
 using namespace stackchan;
 
+namespace {
+
+std::string buildSpeech(const ship_receipts::ScenePayload& beat)
+{
+    if (beat.speaker.empty()) {
+        return beat.line;
+    }
+
+    if (beat.presentation_type == "card") {
+        return fmt::format("{} · {}", beat.speaker, beat.line);
+    }
+
+    return fmt::format("{} says: {}", beat.speaker, beat.line);
+}
+
+const char* resolveEmotion(const ship_receipts::ScenePayload& beat)
+{
+    if (beat.presentation_type == "card") {
+        return "neutral";
+    }
+    return beat.emotion.c_str();
+}
+
+}  // namespace
+
 AppShipReceipts::AppShipReceipts()
 {
     setAppInfo().name = "SHIP.RECEIPTS";
@@ -129,11 +154,12 @@ void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
     auto* display = Board::GetInstance().GetDisplay();
     auto& stack   = GetStackChan();
     auto& motion  = stack.motion();
+    auto speech   = buildSpeech(beat);
 
     if (display) {
         display->SetStatus(beat.title.c_str());
-        display->SetEmotion(beat.emotion.c_str());
-        display->SetChatMessage("assistant", beat.line.c_str());
+        display->SetEmotion(resolveEmotion(beat));
+        display->SetChatMessage("assistant", speech.c_str());
         display->ShowNotification(beat.title.c_str(), 1400);
     }
 
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index ac80bda0..e705d2cb 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -30,10 +30,10 @@ class AppShipReceipts : public mooncake::AppAbility {
 
 private:
     static constexpr std::array<const char*, 4> _scene_json{{
-        R"json({"title":"SHIP.RECEIPTS","line":"Host-driven scenes belong in the app layer.","emotion":"neutral","duration_ms":3600,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":0,"b":0},"play_notification":false})json",
-        R"json({"title":"HEIKE","line":"Bell sounds. All things impermanent.","emotion":"sad","duration_ms":4200,"motion":{"yaw_angle":180,"pitch_angle":170,"speed":320},"led":{"r":64,"g":40,"b":0},"play_notification":true})json",
-        R"json({"title":"ODYSSEY","line":"A card beat can become status plus speech.","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":72},"play_notification":false})json",
-        R"json({"title":"APP BOUNDARY","line":"Motion, LEDs, and audio cues stay generic.","emotion":"doubtful","duration_ms":4200,"motion":{"yaw_angle":0,"pitch_angle":40,"speed":260},"led":{"r":36,"g":0,"b":56},"play_notification":true})json",
+        R"json({"title":"SHIP.RECEIPTS","line":"Host-driven scenes belong in the app layer.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3600,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":0,"b":0},"play_notification":false})json",
+        R"json({"title":"HEIKE","speaker":"BIWA GUIDE","line":"Bell sounds. All things impermanent.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"sad","duration_ms":4200,"motion":{"yaw_angle":180,"pitch_angle":170,"speed":320},"led":{"r":64,"g":40,"b":0},"play_notification":true})json",
+        R"json({"title":"ODYSSEY","line":"A card beat can become status plus speech.","presentation_type":"card","visual_template":"status_card","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":72},"play_notification":false})json",
+        R"json({"title":"APP BOUNDARY","speaker":"STACKCHAN","line":"Motion, LEDs, and audio cues stay generic.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"doubtful","duration_ms":4200,"motion":{"yaw_angle":0,"pitch_angle":40,"speed":260},"led":{"r":36,"g":0,"b":56},"play_notification":true})json",
     }};
 
     bool loadScene(size_t index, ship_receipts::ScenePayload& out_scene);
diff --git a/firmware/main/apps/app_ship_receipts/examples/heike_scene.json b/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
index 83ebf30e..7df90453 100644
--- a/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
+++ b/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
@@ -1,6 +1,9 @@
 {
   "title": "HEIKE",
+  "speaker": "BIWA GUIDE",
   "line": "Bell sounds. All things impermanent.",
+  "presentation_type": "avatar",
+  "visual_template": "avatar_beat",
   "emotion": "sad",
   "duration_ms": 4200,
   "motion": {
diff --git a/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json b/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
index 2c4290c3..37218ded 100644
--- a/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
+++ b/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
@@ -1,6 +1,8 @@
 {
   "title": "ODYSSEY",
   "line": "A card beat can become status plus speech.",
+  "presentation_type": "card",
+  "visual_template": "status_card",
   "emotion": "happy",
   "duration_ms": 3600,
   "motion": {
diff --git a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
index 91cee46c..c2beece5 100644
--- a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
+++ b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
@@ -2,7 +2,10 @@
   "cmd": "shipReceiptsScene",
   "data": {
     "title": "HEIKE",
+    "speaker": "BIWA GUIDE",
     "line": "Bell sounds. All things impermanent.",
+    "presentation_type": "avatar",
+    "visual_template": "avatar_beat",
     "emotion": "sad",
     "duration_ms": 4200,
     "motion": {
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
index fe90cc6a..18fc56b6 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
@@ -50,9 +50,18 @@ bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::strin
     if (doc["line"].is<const char*>()) {
         out_payload.line = doc["line"].as<const char*>();
     }
+    if (doc["speaker"].is<const char*>()) {
+        out_payload.speaker = doc["speaker"].as<const char*>();
+    }
     if (doc["emotion"].is<const char*>()) {
         out_payload.emotion = doc["emotion"].as<const char*>();
     }
+    if (doc["presentation_type"].is<const char*>()) {
+        out_payload.presentation_type = doc["presentation_type"].as<const char*>();
+    }
+    if (doc["visual_template"].is<const char*>()) {
+        out_payload.visual_template = doc["visual_template"].as<const char*>();
+    }
     if (doc["duration_ms"].is<uint32_t>()) {
         out_payload.duration_ms = doc["duration_ms"].as<uint32_t>();
     }
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
index 7cbadbde..da8e7294 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
@@ -10,17 +10,20 @@
 namespace ship_receipts {
 
 struct ScenePayload {
-    std::string title        = "SHIP.RECEIPTS";
-    std::string line         = "";
-    std::string emotion      = "neutral";
-    uint32_t duration_ms     = 3600;
-    int yaw_angle            = 0;
-    int pitch_angle          = 0;
-    int speed                = 320;
-    uint8_t led_r            = 0;
-    uint8_t led_g            = 0;
-    uint8_t led_b            = 0;
-    bool play_notification   = false;
+    std::string title             = "SHIP.RECEIPTS";
+    std::string line              = "";
+    std::string speaker           = "";
+    std::string emotion           = "neutral";
+    std::string presentation_type = "avatar";
+    std::string visual_template   = "";
+    uint32_t duration_ms          = 3600;
+    int yaw_angle                 = 0;
+    int pitch_angle               = 0;
+    int speed                     = 320;
+    uint8_t led_r                 = 0;
+    uint8_t led_g                 = 0;
+    uint8_t led_b                 = 0;
+    bool play_notification        = false;
 };
 
 bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::string* error_message = nullptr);

From 5136802f307acd5d27060c0480aaa68ad078381c Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 06:14:20 -0500
Subject: [PATCH 08/24] docs: clarify ship receipts transport examples

---
 .../main/apps/app_ship_receipts/README.md     | 10 +++++++++
 .../tools/emit_ship_receipts_scene.py         | 21 +++++++++++++++++--
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index f19518c3..31b1a26e 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -84,6 +84,11 @@ surfaces, without inventing a Ship Receipts-specific core protocol first:
 - BLE config writes
 - websocket text messages from the `ship-receipts` sender name
 
+BLE path details:
+
+- service UUID: `e2e5e5e0-1234-5678-1234-56789abcdef0`
+- config characteristic UUID: `e2e5e5e3-1234-5678-1234-56789abcdef0`
+
 Accepted shapes:
 
 - a raw scene object
@@ -149,8 +154,13 @@ Examples:
 ```bash
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format scene
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format command
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format ble-config
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format ws-text
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format transport-note
 ```
 
 The `ws-text` format emits the `name` + `content` shape expected by the app's
 websocket text-message ingest path.
+
+The `ble-config` format is the exact JSON shape accepted by the existing BLE
+config characteristic.
diff --git a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
index ca7e67ba..ce36df5a 100755
--- a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
+++ b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
@@ -19,20 +19,37 @@ def load_scene(name: str) -> dict:
 def build_output(scene: dict, fmt: str) -> dict:
     if fmt == "scene":
         return scene
-    if fmt == "command":
+    if fmt in {"command", "ble-config"}:
         return {"cmd": "shipReceiptsScene", "data": scene}
     if fmt == "ws-text":
         return {
             "name": "ship-receipts",
             "content": json.dumps({"cmd": "shipReceiptsScene", "data": scene}, ensure_ascii=False),
         }
+    if fmt == "transport-note":
+        return {
+            "ble": {
+                "service_uuid": "e2e5e5e0-1234-5678-1234-56789abcdef0",
+                "characteristic_uuid": "e2e5e5e3-1234-5678-1234-56789abcdef0",
+                "shape": "ble-config",
+            },
+            "websocket": {
+                "surface": "text-message",
+                "sender_name": "ship-receipts",
+                "shape": "ws-text",
+            },
+        }
     raise ValueError(f"unknown format: {fmt}")
 
 
 def main() -> None:
     parser = argparse.ArgumentParser(description="Emit Ship Receipts app scene payloads for StackChan")
     parser.add_argument("--scene", choices=sorted(SCENES.keys()), default="heike")
-    parser.add_argument("--format", choices=["scene", "command", "ws-text"], default="command")
+    parser.add_argument(
+        "--format",
+        choices=["scene", "command", "ble-config", "ws-text", "transport-note"],
+        default="command",
+    )
     args = parser.parse_args()
 
     scene = load_scene(args.scene)

From 4be870bd33b45b66eddc858c64d9d90983aa30d7 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 06:20:15 -0500
Subject: [PATCH 09/24] feat: add ship receipts scene metadata

---
 firmware/main/apps/app_ship_receipts/README.md        | 11 +++++++++++
 .../main/apps/app_ship_receipts/app_ship_receipts.cpp |  5 +++++
 .../main/apps/app_ship_receipts/app_ship_receipts.h   |  8 ++++----
 .../apps/app_ship_receipts/examples/heike_scene.json  |  2 ++
 .../app_ship_receipts/examples/odyssey_scene.json     |  2 ++
 .../examples/ship_receipts_scene_command.json         |  2 ++
 .../apps/app_ship_receipts/ship_receipts_scene.cpp    |  6 ++++++
 .../main/apps/app_ship_receipts/ship_receipts_scene.h |  2 ++
 .../tools/emit_ship_receipts_scene.py                 |  9 ++++++++-
 9 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 31b1a26e..a73a2ab8 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -116,6 +116,8 @@ scene semantics.
 
 The app-local scene payload currently understands:
 
+- `id` (optional scene identity for host/app orchestration)
+- `mode` (optional app mode such as `heike` or `odyssey`)
 - `title`
 - `line`
 - `speaker` (optional)
@@ -136,6 +138,15 @@ Current rendering behavior:
   - forces a neutral face
   - treats speech as supporting card copy instead of character dialogue
 
+Current metadata behavior:
+
+- `id`
+  - preserved so host and app can refer to a stable beat identity
+  - logged by the app when a scene is loaded/applied
+- `mode`
+  - preserved so higher-level Ship Receipts mode selection can stay app-local
+  - logged by the app when a scene is loaded/applied
+
 ## Example payloads and host helper
 
 Checked-in examples live here:
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 03351223..96a7fbab 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -146,6 +146,8 @@ bool AppShipReceipts::loadScene(size_t index, ship_receipts::ScenePayload& out_s
                         error_message.c_str());
         return false;
     }
+    mclog::tagInfo(getAppInfo().name, "loaded scene id='{}' mode='{}' presentation='{}'", out_scene.scene_id,
+                   out_scene.mode, out_scene.presentation_type);
     return true;
 }
 
@@ -163,6 +165,9 @@ void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
         display->ShowNotification(beat.title.c_str(), 1400);
     }
 
+    mclog::tagInfo(getAppInfo().name, "apply beat id='{}' mode='{}' template='{}'", beat.scene_id, beat.mode,
+                   beat.visual_template);
+
     if (beat.play_notification) {
         hal_bridge::app_play_sound(OGG_NEW_NOTIFICATION);
     }
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index e705d2cb..9c1eede6 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -30,10 +30,10 @@ class AppShipReceipts : public mooncake::AppAbility {
 
 private:
     static constexpr std::array<const char*, 4> _scene_json{{
-        R"json({"title":"SHIP.RECEIPTS","line":"Host-driven scenes belong in the app layer.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3600,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":0,"b":0},"play_notification":false})json",
-        R"json({"title":"HEIKE","speaker":"BIWA GUIDE","line":"Bell sounds. All things impermanent.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"sad","duration_ms":4200,"motion":{"yaw_angle":180,"pitch_angle":170,"speed":320},"led":{"r":64,"g":40,"b":0},"play_notification":true})json",
-        R"json({"title":"ODYSSEY","line":"A card beat can become status plus speech.","presentation_type":"card","visual_template":"status_card","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":72},"play_notification":false})json",
-        R"json({"title":"APP BOUNDARY","speaker":"STACKCHAN","line":"Motion, LEDs, and audio cues stay generic.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"doubtful","duration_ms":4200,"motion":{"yaw_angle":0,"pitch_angle":40,"speed":260},"led":{"r":36,"g":0,"b":56},"play_notification":true})json",
+        R"json({"id":"app-shell-card","mode":"ship-receipts-shell","title":"SHIP.RECEIPTS","line":"Host-driven scenes belong in the app layer.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3600,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":0,"b":0},"play_notification":false})json",
+        R"json({"id":"heike-avatar-1","mode":"heike","title":"HEIKE","speaker":"BIWA GUIDE","line":"Bell sounds. All things impermanent.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"sad","duration_ms":4200,"motion":{"yaw_angle":180,"pitch_angle":170,"speed":320},"led":{"r":64,"g":40,"b":0},"play_notification":true})json",
+        R"json({"id":"odyssey-card-1","mode":"odyssey","title":"ODYSSEY","line":"A card beat can become status plus speech.","presentation_type":"card","visual_template":"status_card","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":72},"play_notification":false})json",
+        R"json({"id":"app-boundary-avatar","mode":"ship-receipts-shell","title":"APP BOUNDARY","speaker":"STACKCHAN","line":"Motion, LEDs, and audio cues stay generic.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"doubtful","duration_ms":4200,"motion":{"yaw_angle":0,"pitch_angle":40,"speed":260},"led":{"r":36,"g":0,"b":56},"play_notification":true})json",
     }};
 
     bool loadScene(size_t index, ship_receipts::ScenePayload& out_scene);
diff --git a/firmware/main/apps/app_ship_receipts/examples/heike_scene.json b/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
index 7df90453..6b116e2a 100644
--- a/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
+++ b/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
@@ -1,4 +1,6 @@
 {
+  "id": "heike-avatar-1",
+  "mode": "heike",
   "title": "HEIKE",
   "speaker": "BIWA GUIDE",
   "line": "Bell sounds. All things impermanent.",
diff --git a/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json b/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
index 37218ded..c4466328 100644
--- a/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
+++ b/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
@@ -1,4 +1,6 @@
 {
+  "id": "odyssey-card-1",
+  "mode": "odyssey",
   "title": "ODYSSEY",
   "line": "A card beat can become status plus speech.",
   "presentation_type": "card",
diff --git a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
index c2beece5..b2493643 100644
--- a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
+++ b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
@@ -1,6 +1,8 @@
 {
   "cmd": "shipReceiptsScene",
   "data": {
+    "id": "heike-avatar-1",
+    "mode": "heike",
     "title": "HEIKE",
     "speaker": "BIWA GUIDE",
     "line": "Bell sounds. All things impermanent.",
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
index 18fc56b6..8a17a08e 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
@@ -44,6 +44,12 @@ bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::strin
         return false;
     }
 
+    if (doc["id"].is<const char*>()) {
+        out_payload.scene_id = doc["id"].as<const char*>();
+    }
+    if (doc["mode"].is<const char*>()) {
+        out_payload.mode = doc["mode"].as<const char*>();
+    }
     if (doc["title"].is<const char*>()) {
         out_payload.title = doc["title"].as<const char*>();
     }
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
index da8e7294..89706816 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
@@ -10,6 +10,8 @@
 namespace ship_receipts {
 
 struct ScenePayload {
+    std::string scene_id          = "";
+    std::string mode              = "";
     std::string title             = "SHIP.RECEIPTS";
     std::string line              = "";
     std::string speaker           = "";
diff --git a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
index ce36df5a..60ddb819 100755
--- a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
+++ b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
@@ -39,6 +39,13 @@ def build_output(scene: dict, fmt: str) -> dict:
                 "shape": "ws-text",
             },
         }
+    if fmt == "metadata":
+        return {
+            "id": scene.get("id", ""),
+            "mode": scene.get("mode", ""),
+            "presentation_type": scene.get("presentation_type", ""),
+            "visual_template": scene.get("visual_template", ""),
+        }
     raise ValueError(f"unknown format: {fmt}")
 
 
@@ -47,7 +54,7 @@ def main() -> None:
     parser.add_argument("--scene", choices=sorted(SCENES.keys()), default="heike")
     parser.add_argument(
         "--format",
-        choices=["scene", "command", "ble-config", "ws-text", "transport-note"],
+        choices=["scene", "command", "ble-config", "ws-text", "transport-note", "metadata"],
         default="command",
     )
     args = parser.parse_args()

From f0844470acafe3db26d8a48e52b9f4fb80f5abb7 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 06:56:40 -0500
Subject: [PATCH 10/24] feat: add ship receipts sequence states

---
 .../main/apps/app_ship_receipts/README.md     | 13 ++++++++
 .../app_ship_receipts/app_ship_receipts.cpp   | 33 ++++++++++++++++---
 .../app_ship_receipts/app_ship_receipts.h     |  8 +++++
 3 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index a73a2ab8..0bdb5929 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -112,6 +112,19 @@ Accepted shapes:
 This keeps the transport generic while letting the Ship Receipts app own its
 scene semantics.
 
+## Current sequence states
+
+The app currently distinguishes between two app-local sequencing states:
+
+- `DemoRotation`
+  - rotates through built-in sample beats
+- `LiveOverride`
+  - temporarily applies an externally injected scene from BLE or websocket text
+  - when that beat's `duration_ms` expires, the app returns to demo rotation
+
+This keeps "what the app is doing right now" as app state instead of pushing
+Ship Receipts sequencing policy down into StackChan core.
+
 ## Current scene fields
 
 The app-local scene payload currently understands:
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 96a7fbab..6c023643 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -95,10 +95,7 @@ void AppShipReceipts::onOpen()
         }
     });
 
-    _beat_index = 0;
-    if (loadScene(_beat_index, _active_scene)) {
-        applyBeat(_active_scene);
-    }
+    enterDemoRotation();
     view::pop_a_toast("Ship Receipts demo shell ready", view::ToastType::Info, 1800);
 }
 
@@ -117,7 +114,11 @@ void AppShipReceipts::onRunning()
 
     if (_beat_started_at > 0) {
         if (GetHAL().millis() - _beat_started_at >= _active_scene.duration_ms) {
-            advanceBeat();
+            if (_sequence_state == SequenceState::LiveOverride) {
+                resumeDemoRotation();
+            } else {
+                advanceBeat();
+            }
         }
     }
 }
@@ -177,6 +178,26 @@ void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
     _beat_started_at = GetHAL().millis();
 }
 
+void AppShipReceipts::enterDemoRotation()
+{
+    _sequence_state = SequenceState::DemoRotation;
+    _beat_index     = 0;
+    if (loadScene(_beat_index, _active_scene)) {
+        applyBeat(_active_scene);
+    }
+    mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation");
+}
+
+void AppShipReceipts::resumeDemoRotation()
+{
+    _sequence_state = SequenceState::DemoRotation;
+    _beat_index     = (_beat_index + 1) % _scene_json.size();
+    if (loadScene(_beat_index, _active_scene)) {
+        applyBeat(_active_scene);
+    }
+    mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation (resumed)");
+}
+
 void AppShipReceipts::enqueueSceneJson(std::string json)
 {
     std::lock_guard<std::mutex> lock(_queue_mutex);
@@ -204,8 +225,10 @@ void AppShipReceipts::applyQueuedSceneJson(const std::string& json)
         return;
     }
 
+    _sequence_state = SequenceState::LiveOverride;
     _active_scene = std::move(parsed);
     applyBeat(_active_scene);
+    mclog::tagInfo(getAppInfo().name, "sequence state -> live override");
     view::pop_a_toast("Ship Receipts scene received", view::ToastType::Info, 1200);
 }
 
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index 9c1eede6..e8493d10 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -29,6 +29,11 @@ class AppShipReceipts : public mooncake::AppAbility {
     void onClose() override;
 
 private:
+    enum class SequenceState {
+        DemoRotation = 0,
+        LiveOverride,
+    };
+
     static constexpr std::array<const char*, 4> _scene_json{{
         R"json({"id":"app-shell-card","mode":"ship-receipts-shell","title":"SHIP.RECEIPTS","line":"Host-driven scenes belong in the app layer.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3600,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":0,"b":0},"play_notification":false})json",
         R"json({"id":"heike-avatar-1","mode":"heike","title":"HEIKE","speaker":"BIWA GUIDE","line":"Bell sounds. All things impermanent.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"sad","duration_ms":4200,"motion":{"yaw_angle":180,"pitch_angle":170,"speed":320},"led":{"r":64,"g":40,"b":0},"play_notification":true})json",
@@ -41,6 +46,8 @@ class AppShipReceipts : public mooncake::AppAbility {
     bool dequeueSceneJson(std::string& out_json);
     void applyQueuedSceneJson(const std::string& json);
     void applyBeat(const ship_receipts::ScenePayload& beat);
+    void enterDemoRotation();
+    void resumeDemoRotation();
     void clearBeat();
     void advanceBeat();
 
@@ -48,5 +55,6 @@ class AppShipReceipts : public mooncake::AppAbility {
     std::deque<std::string> _pending_scene_json;
     uint32_t _beat_started_at = 0;
     size_t _beat_index        = 0;
+    SequenceState _sequence_state = SequenceState::DemoRotation;
     ship_receipts::ScenePayload _active_scene{};
 };

From c8f7c06d59f7807b01469d79fec37925ead3b903 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 07:17:41 -0500
Subject: [PATCH 11/24] feat: support sticky live ship receipts scenes

---
 firmware/main/apps/app_ship_receipts/README.md |  8 ++++++++
 .../app_ship_receipts/app_ship_receipts.cpp    | 18 ++++++++++++------
 .../apps/app_ship_receipts/app_ship_receipts.h |  1 +
 .../examples/heike_scene.json                  |  3 ++-
 .../examples/odyssey_scene.json                |  3 ++-
 .../examples/ship_receipts_scene_command.json  |  3 ++-
 .../app_ship_receipts/ship_receipts_scene.cpp  |  3 +++
 .../app_ship_receipts/ship_receipts_scene.h    |  1 +
 .../tools/emit_ship_receipts_scene.py          |  1 +
 9 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 0bdb5929..29d49f32 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -121,6 +121,10 @@ The app currently distinguishes between two app-local sequencing states:
 - `LiveOverride`
   - temporarily applies an externally injected scene from BLE or websocket text
   - when that beat's `duration_ms` expires, the app returns to demo rotation
+- `LiveSticky`
+  - applies an externally injected scene that stays active after its first
+    duration window
+  - remains active until another scene replaces it or the app is closed
 
 This keeps "what the app is doing right now" as app state instead of pushing
 Ship Receipts sequencing policy down into StackChan core.
@@ -141,6 +145,7 @@ The app-local scene payload currently understands:
 - `motion`
 - `led`
 - `play_notification`
+- `sticky`
 
 Current rendering behavior:
 
@@ -159,6 +164,9 @@ Current metadata behavior:
 - `mode`
   - preserved so higher-level Ship Receipts mode selection can stay app-local
   - logged by the app when a scene is loaded/applied
+- `sticky`
+  - `false` means a live injected scene expires back to demo rotation
+  - `true` means a live injected scene remains active until replaced
 
 ## Example payloads and host helper
 
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 6c023643..91f1ce44 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -114,7 +114,9 @@ void AppShipReceipts::onRunning()
 
     if (_beat_started_at > 0) {
         if (GetHAL().millis() - _beat_started_at >= _active_scene.duration_ms) {
-            if (_sequence_state == SequenceState::LiveOverride) {
+            if (_sequence_state == SequenceState::LiveSticky) {
+                _beat_started_at = 0;
+            } else if (_sequence_state == SequenceState::LiveOverride) {
                 resumeDemoRotation();
             } else {
                 advanceBeat();
@@ -166,8 +168,8 @@ void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
         display->ShowNotification(beat.title.c_str(), 1400);
     }
 
-    mclog::tagInfo(getAppInfo().name, "apply beat id='{}' mode='{}' template='{}'", beat.scene_id, beat.mode,
-                   beat.visual_template);
+    mclog::tagInfo(getAppInfo().name, "apply beat id='{}' mode='{}' template='{}' sticky={}", beat.scene_id,
+                   beat.mode, beat.visual_template, beat.sticky);
 
     if (beat.play_notification) {
         hal_bridge::app_play_sound(OGG_NEW_NOTIFICATION);
@@ -225,11 +227,15 @@ void AppShipReceipts::applyQueuedSceneJson(const std::string& json)
         return;
     }
 
-    _sequence_state = SequenceState::LiveOverride;
+    _sequence_state = parsed.sticky ? SequenceState::LiveSticky : SequenceState::LiveOverride;
     _active_scene = std::move(parsed);
     applyBeat(_active_scene);
-    mclog::tagInfo(getAppInfo().name, "sequence state -> live override");
-    view::pop_a_toast("Ship Receipts scene received", view::ToastType::Info, 1200);
+    mclog::tagInfo(getAppInfo().name, "sequence state -> {}", _sequence_state == SequenceState::LiveSticky
+                                                              ? "live sticky"
+                                                              : "live override");
+    view::pop_a_toast(_sequence_state == SequenceState::LiveSticky ? "Sticky Ship Receipts scene received"
+                                                                   : "Ship Receipts scene received",
+                      view::ToastType::Info, 1200);
 }
 
 void AppShipReceipts::clearBeat()
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index e8493d10..7a045905 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -32,6 +32,7 @@ class AppShipReceipts : public mooncake::AppAbility {
     enum class SequenceState {
         DemoRotation = 0,
         LiveOverride,
+        LiveSticky,
     };
 
     static constexpr std::array<const char*, 4> _scene_json{{
diff --git a/firmware/main/apps/app_ship_receipts/examples/heike_scene.json b/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
index 6b116e2a..661945f7 100644
--- a/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
+++ b/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
@@ -18,5 +18,6 @@
     "g": 40,
     "b": 0
   },
-  "play_notification": true
+  "play_notification": true,
+  "sticky": false
 }
diff --git a/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json b/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
index c4466328..029c47b8 100644
--- a/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
+++ b/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
@@ -17,5 +17,6 @@
     "g": 40,
     "b": 72
   },
-  "play_notification": false
+  "play_notification": false,
+  "sticky": false
 }
diff --git a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
index b2493643..4abf616b 100644
--- a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
+++ b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
@@ -20,6 +20,7 @@
       "g": 40,
       "b": 0
     },
-    "play_notification": true
+    "play_notification": true,
+    "sticky": false
   }
 }
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
index 8a17a08e..878c867e 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
@@ -74,6 +74,9 @@ bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::strin
     if (doc["play_notification"].is<bool>()) {
         out_payload.play_notification = doc["play_notification"].as<bool>();
     }
+    if (doc["sticky"].is<bool>()) {
+        out_payload.sticky = doc["sticky"].as<bool>();
+    }
 
     if (doc["motion"].is<ArduinoJson::JsonObject>()) {
         auto motion = doc["motion"].as<ArduinoJson::JsonObject>();
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
index 89706816..3c9e8309 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
@@ -26,6 +26,7 @@ struct ScenePayload {
     uint8_t led_g                 = 0;
     uint8_t led_b                 = 0;
     bool play_notification        = false;
+    bool sticky                   = false;
 };
 
 bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::string* error_message = nullptr);
diff --git a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
index 60ddb819..16766f37 100755
--- a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
+++ b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
@@ -45,6 +45,7 @@ def build_output(scene: dict, fmt: str) -> dict:
             "mode": scene.get("mode", ""),
             "presentation_type": scene.get("presentation_type", ""),
             "visual_template": scene.get("visual_template", ""),
+            "sticky": scene.get("sticky", False),
         }
     raise ValueError(f"unknown format: {fmt}")
 

From 95541d05f14526b2a5bb91ef32c8eb49d32249d6 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 07:27:31 -0500
Subject: [PATCH 12/24] feat: add ship receipts resume-demo command

---
 .../main/apps/app_ship_receipts/README.md     | 13 ++++++++
 .../app_ship_receipts/app_ship_receipts.cpp   | 14 +++++++--
 .../app_ship_receipts/app_ship_receipts.h     |  2 +-
 .../ship_receipts_resume_demo_command.json    |  3 ++
 .../app_ship_receipts/ship_receipts_scene.cpp | 31 +++++++++++++++++++
 .../app_ship_receipts/ship_receipts_scene.h   |  6 ++++
 .../tools/emit_ship_receipts_scene.py         |  4 ++-
 7 files changed, 69 insertions(+), 4 deletions(-)
 create mode 100644 firmware/main/apps/app_ship_receipts/examples/ship_receipts_resume_demo_command.json

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 29d49f32..905bb6c6 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -112,6 +112,17 @@ Accepted shapes:
 This keeps the transport generic while letting the Ship Receipts app own its
 scene semantics.
 
+Supported control envelope:
+
+```json
+{
+  "cmd": "shipReceiptsResumeDemo"
+}
+```
+
+That command explicitly releases any current live override or sticky scene and
+returns the app to built-in demo rotation.
+
 ## Current sequence states
 
 The app currently distinguishes between two app-local sequencing states:
@@ -175,6 +186,7 @@ Checked-in examples live here:
 - [examples/heike_scene.json](./examples/heike_scene.json)
 - [examples/odyssey_scene.json](./examples/odyssey_scene.json)
 - [examples/ship_receipts_scene_command.json](./examples/ship_receipts_scene_command.json)
+- [examples/ship_receipts_resume_demo_command.json](./examples/ship_receipts_resume_demo_command.json)
 
 A tiny helper can emit the supported payload shapes without adding any new
 dependencies:
@@ -189,6 +201,7 @@ python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py -
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format ble-config
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format ws-text
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format transport-note
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format resume-demo
 ```
 
 The `ws-text` format emits the `name` + `content` shape expected by the app's
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 91f1ce44..7ec65d2b 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -105,7 +105,7 @@ void AppShipReceipts::onRunning()
 
     std::string queued_scene;
     if (dequeueSceneJson(queued_scene)) {
-        applyQueuedSceneJson(queued_scene);
+        handleQueuedCommand(queued_scene);
     }
 
     GetStackChan().update();
@@ -217,8 +217,18 @@ bool AppShipReceipts::dequeueSceneJson(std::string& out_json)
     return true;
 }
 
-void AppShipReceipts::applyQueuedSceneJson(const std::string& json)
+void AppShipReceipts::handleQueuedCommand(const std::string& json)
 {
+    ship_receipts::ControlAction action;
+    std::string control_error;
+    if (ship_receipts::parse_control_command(json.c_str(), action, &control_error)) {
+        if (action == ship_receipts::ControlAction::ResumeDemo) {
+            resumeDemoRotation();
+            view::pop_a_toast("Ship Receipts demo rotation resumed", view::ToastType::Info, 1200);
+            return;
+        }
+    }
+
     ship_receipts::ScenePayload parsed;
     std::string error_message;
     if (!ship_receipts::parse_scene_command(json.c_str(), parsed, &error_message)) {
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index 7a045905..06bb67e1 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -45,7 +45,7 @@ class AppShipReceipts : public mooncake::AppAbility {
     bool loadScene(size_t index, ship_receipts::ScenePayload& out_scene);
     void enqueueSceneJson(std::string json);
     bool dequeueSceneJson(std::string& out_json);
-    void applyQueuedSceneJson(const std::string& json);
+    void handleQueuedCommand(const std::string& json);
     void applyBeat(const ship_receipts::ScenePayload& beat);
     void enterDemoRotation();
     void resumeDemoRotation();
diff --git a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_resume_demo_command.json b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_resume_demo_command.json
new file mode 100644
index 00000000..76ee9569
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_resume_demo_command.json
@@ -0,0 +1,3 @@
+{
+  "cmd": "shipReceiptsResumeDemo"
+}
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
index 878c867e..c9f77c76 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
@@ -135,4 +135,35 @@ bool parse_scene_command(const char* json, ScenePayload& out_payload, std::strin
     return parse_scene_payload(json, out_payload, error_message);
 }
 
+bool parse_control_command(const char* json, ControlAction& out_action, std::string* error_message)
+{
+    out_action = ControlAction::None;
+
+    if (!json) {
+        set_error(error_message, "control command was null");
+        return false;
+    }
+
+    ArduinoJson::JsonDocument doc;
+    auto error = ArduinoJson::deserializeJson(doc, json);
+    if (error) {
+        set_error(error_message, error.c_str());
+        return false;
+    }
+
+    if (!doc["cmd"].is<const char*>()) {
+        set_error(error_message, "control command missing cmd");
+        return false;
+    }
+
+    auto cmd = std::string_view(doc["cmd"].as<const char*>());
+    if (cmd == "shipReceiptsResumeDemo") {
+        out_action = ControlAction::ResumeDemo;
+        return true;
+    }
+
+    set_error(error_message, "unknown ship receipts control command");
+    return false;
+}
+
 }  // namespace ship_receipts
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
index 3c9e8309..def9d76a 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
@@ -9,6 +9,11 @@
 
 namespace ship_receipts {
 
+enum class ControlAction {
+    None = 0,
+    ResumeDemo,
+};
+
 struct ScenePayload {
     std::string scene_id          = "";
     std::string mode              = "";
@@ -31,5 +36,6 @@ struct ScenePayload {
 
 bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::string* error_message = nullptr);
 bool parse_scene_command(const char* json, ScenePayload& out_payload, std::string* error_message = nullptr);
+bool parse_control_command(const char* json, ControlAction& out_action, std::string* error_message = nullptr);
 
 }  // namespace ship_receipts
diff --git a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
index 16766f37..6ff0c6c8 100755
--- a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
+++ b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
@@ -21,6 +21,8 @@ def build_output(scene: dict, fmt: str) -> dict:
         return scene
     if fmt in {"command", "ble-config"}:
         return {"cmd": "shipReceiptsScene", "data": scene}
+    if fmt == "resume-demo":
+        return {"cmd": "shipReceiptsResumeDemo"}
     if fmt == "ws-text":
         return {
             "name": "ship-receipts",
@@ -55,7 +57,7 @@ def main() -> None:
     parser.add_argument("--scene", choices=sorted(SCENES.keys()), default="heike")
     parser.add_argument(
         "--format",
-        choices=["scene", "command", "ble-config", "ws-text", "transport-note", "metadata"],
+        choices=["scene", "command", "ble-config", "ws-text", "transport-note", "metadata", "resume-demo"],
         default="command",
     )
     args = parser.parse_args()

From 89be29f6187100730bd7045798fc18a4bc0d67aa Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 15:07:57 -0500
Subject: [PATCH 13/24] feat: add ship receipts status command

---
 .../main/apps/app_ship_receipts/README.md     | 17 ++++++++++++
 .../app_ship_receipts/app_ship_receipts.cpp   | 27 ++++++++++++++++++-
 .../app_ship_receipts/app_ship_receipts.h     |  2 ++
 .../ship_receipts_show_status_command.json    |  3 +++
 .../app_ship_receipts/ship_receipts_scene.cpp |  4 +++
 .../app_ship_receipts/ship_receipts_scene.h   |  1 +
 .../tools/emit_ship_receipts_scene.py         |  4 ++-
 7 files changed, 56 insertions(+), 2 deletions(-)
 create mode 100644 firmware/main/apps/app_ship_receipts/examples/ship_receipts_show_status_command.json

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 905bb6c6..8c39c91e 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -123,6 +123,21 @@ Supported control envelope:
 That command explicitly releases any current live override or sticky scene and
 returns the app to built-in demo rotation.
 
+Additional status command:
+
+```json
+{
+  "cmd": "shipReceiptsShowStatus"
+}
+```
+
+That command causes the app to surface a short status summary using current
+app-local state, including:
+
+- sequence state
+- current mode
+- current scene id
+
 ## Current sequence states
 
 The app currently distinguishes between two app-local sequencing states:
@@ -187,6 +202,7 @@ Checked-in examples live here:
 - [examples/odyssey_scene.json](./examples/odyssey_scene.json)
 - [examples/ship_receipts_scene_command.json](./examples/ship_receipts_scene_command.json)
 - [examples/ship_receipts_resume_demo_command.json](./examples/ship_receipts_resume_demo_command.json)
+- [examples/ship_receipts_show_status_command.json](./examples/ship_receipts_show_status_command.json)
 
 A tiny helper can emit the supported payload shapes without adding any new
 dependencies:
@@ -202,6 +218,7 @@ python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py -
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format ws-text
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format transport-note
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format resume-demo
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format show-status
 ```
 
 The `ws-text` format emits the `name` + `content` shape expected by the app's
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 7ec65d2b..607cff1c 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -40,7 +40,6 @@ const char* resolveEmotion(const ship_receipts::ScenePayload& beat)
     }
     return beat.emotion.c_str();
 }
-
 }  // namespace
 
 AppShipReceipts::AppShipReceipts()
@@ -200,6 +199,26 @@ void AppShipReceipts::resumeDemoRotation()
     mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation (resumed)");
 }
 
+const char* AppShipReceipts::sequenceStateLabel() const
+{
+    switch (_sequence_state) {
+        case SequenceState::DemoRotation:
+            return "demo";
+        case SequenceState::LiveOverride:
+            return "live";
+        case SequenceState::LiveSticky:
+            return "sticky";
+    }
+    return "unknown";
+}
+
+std::string AppShipReceipts::statusSummary() const
+{
+    return fmt::format("state={} mode={} scene={}", sequenceStateLabel(),
+                       _active_scene.mode.empty() ? "-" : _active_scene.mode,
+                       _active_scene.scene_id.empty() ? "-" : _active_scene.scene_id);
+}
+
 void AppShipReceipts::enqueueSceneJson(std::string json)
 {
     std::lock_guard<std::mutex> lock(_queue_mutex);
@@ -227,6 +246,12 @@ void AppShipReceipts::handleQueuedCommand(const std::string& json)
             view::pop_a_toast("Ship Receipts demo rotation resumed", view::ToastType::Info, 1200);
             return;
         }
+        if (action == ship_receipts::ControlAction::ShowStatus) {
+            auto summary = statusSummary();
+            mclog::tagInfo(getAppInfo().name, "status -> {}", summary);
+            view::pop_a_toast(summary, view::ToastType::Info, 1800);
+            return;
+        }
     }
 
     ship_receipts::ScenePayload parsed;
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index 06bb67e1..78ba1280 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -49,6 +49,8 @@ class AppShipReceipts : public mooncake::AppAbility {
     void applyBeat(const ship_receipts::ScenePayload& beat);
     void enterDemoRotation();
     void resumeDemoRotation();
+    const char* sequenceStateLabel() const;
+    std::string statusSummary() const;
     void clearBeat();
     void advanceBeat();
 
diff --git a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_show_status_command.json b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_show_status_command.json
new file mode 100644
index 00000000..6226e481
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_show_status_command.json
@@ -0,0 +1,3 @@
+{
+  "cmd": "shipReceiptsShowStatus"
+}
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
index c9f77c76..cb09816d 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
@@ -161,6 +161,10 @@ bool parse_control_command(const char* json, ControlAction& out_action, std::str
         out_action = ControlAction::ResumeDemo;
         return true;
     }
+    if (cmd == "shipReceiptsShowStatus") {
+        out_action = ControlAction::ShowStatus;
+        return true;
+    }
 
     set_error(error_message, "unknown ship receipts control command");
     return false;
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
index def9d76a..c556e4d0 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
@@ -12,6 +12,7 @@ namespace ship_receipts {
 enum class ControlAction {
     None = 0,
     ResumeDemo,
+    ShowStatus,
 };
 
 struct ScenePayload {
diff --git a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
index 6ff0c6c8..69fbaacb 100755
--- a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
+++ b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
@@ -23,6 +23,8 @@ def build_output(scene: dict, fmt: str) -> dict:
         return {"cmd": "shipReceiptsScene", "data": scene}
     if fmt == "resume-demo":
         return {"cmd": "shipReceiptsResumeDemo"}
+    if fmt == "show-status":
+        return {"cmd": "shipReceiptsShowStatus"}
     if fmt == "ws-text":
         return {
             "name": "ship-receipts",
@@ -57,7 +59,7 @@ def main() -> None:
     parser.add_argument("--scene", choices=sorted(SCENES.keys()), default="heike")
     parser.add_argument(
         "--format",
-        choices=["scene", "command", "ble-config", "ws-text", "transport-note", "metadata", "resume-demo"],
+        choices=["scene", "command", "ble-config", "ws-text", "transport-note", "metadata", "resume-demo", "show-status"],
         default="command",
     )
     args = parser.parse_args()

From c40b8f9186066910afd76b5d83e8c3e7ff5c99d6 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Wed, 27 May 2026 21:01:46 -0500
Subject: [PATCH 14/24] feat: add ship receipts set-mode command

---
 .../main/apps/app_ship_receipts/README.md     | 14 +++++++++
 .../app_ship_receipts/app_ship_receipts.cpp   | 31 ++++++++++++++++++-
 .../app_ship_receipts/app_ship_receipts.h     |  1 +
 .../ship_receipts_set_mode_command.json       |  4 +++
 .../app_ship_receipts/ship_receipts_scene.cpp | 17 +++++++++-
 .../app_ship_receipts/ship_receipts_scene.h   |  4 ++-
 .../tools/emit_ship_receipts_scene.py         |  4 ++-
 7 files changed, 71 insertions(+), 4 deletions(-)
 create mode 100644 firmware/main/apps/app_ship_receipts/examples/ship_receipts_set_mode_command.json

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 8c39c91e..e5c488bf 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -138,6 +138,18 @@ app-local state, including:
 - current mode
 - current scene id
 
+Mode selection command:
+
+```json
+{
+  "cmd": "shipReceiptsSetMode",
+  "mode": "heike"
+}
+```
+
+That command explicitly jumps the built-in demo rotation to the first beat for
+the requested Ship Receipts mode.
+
 ## Current sequence states
 
 The app currently distinguishes between two app-local sequencing states:
@@ -203,6 +215,7 @@ Checked-in examples live here:
 - [examples/ship_receipts_scene_command.json](./examples/ship_receipts_scene_command.json)
 - [examples/ship_receipts_resume_demo_command.json](./examples/ship_receipts_resume_demo_command.json)
 - [examples/ship_receipts_show_status_command.json](./examples/ship_receipts_show_status_command.json)
+- [examples/ship_receipts_set_mode_command.json](./examples/ship_receipts_set_mode_command.json)
 
 A tiny helper can emit the supported payload shapes without adding any new
 dependencies:
@@ -219,6 +232,7 @@ python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py -
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format transport-note
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format resume-demo
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format show-status
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format set-mode
 ```
 
 The `ws-text` format emits the `name` + `content` shape expected by the app's
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 607cff1c..fe33c79a 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -199,6 +199,25 @@ void AppShipReceipts::resumeDemoRotation()
     mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation (resumed)");
 }
 
+bool AppShipReceipts::setDemoMode(std::string_view mode)
+{
+    for (size_t i = 0; i < _scene_json.size(); ++i) {
+        ship_receipts::ScenePayload candidate;
+        if (!loadScene(i, candidate)) {
+            continue;
+        }
+        if (candidate.mode == mode) {
+            _sequence_state = SequenceState::DemoRotation;
+            _beat_index     = i;
+            _active_scene   = std::move(candidate);
+            applyBeat(_active_scene);
+            mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation (mode={})", mode);
+            return true;
+        }
+    }
+    return false;
+}
+
 const char* AppShipReceipts::sequenceStateLabel() const
 {
     switch (_sequence_state) {
@@ -239,8 +258,9 @@ bool AppShipReceipts::dequeueSceneJson(std::string& out_json)
 void AppShipReceipts::handleQueuedCommand(const std::string& json)
 {
     ship_receipts::ControlAction action;
+    std::string mode;
     std::string control_error;
-    if (ship_receipts::parse_control_command(json.c_str(), action, &control_error)) {
+    if (ship_receipts::parse_control_command(json.c_str(), action, &mode, &control_error)) {
         if (action == ship_receipts::ControlAction::ResumeDemo) {
             resumeDemoRotation();
             view::pop_a_toast("Ship Receipts demo rotation resumed", view::ToastType::Info, 1200);
@@ -252,6 +272,15 @@ void AppShipReceipts::handleQueuedCommand(const std::string& json)
             view::pop_a_toast(summary, view::ToastType::Info, 1800);
             return;
         }
+        if (action == ship_receipts::ControlAction::SetMode) {
+            if (setDemoMode(mode)) {
+                view::pop_a_toast(fmt::format("Ship Receipts mode -> {}", mode), view::ToastType::Info, 1500);
+            } else {
+                view::pop_a_toast(fmt::format("Unknown Ship Receipts mode: {}", mode), view::ToastType::Warning,
+                                  1800);
+            }
+            return;
+        }
     }
 
     ship_receipts::ScenePayload parsed;
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index 78ba1280..dec7553e 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -49,6 +49,7 @@ class AppShipReceipts : public mooncake::AppAbility {
     void applyBeat(const ship_receipts::ScenePayload& beat);
     void enterDemoRotation();
     void resumeDemoRotation();
+    bool setDemoMode(std::string_view mode);
     const char* sequenceStateLabel() const;
     std::string statusSummary() const;
     void clearBeat();
diff --git a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_set_mode_command.json b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_set_mode_command.json
new file mode 100644
index 00000000..579fee5d
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_set_mode_command.json
@@ -0,0 +1,4 @@
+{
+  "cmd": "shipReceiptsSetMode",
+  "mode": "heike"
+}
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
index cb09816d..b383316a 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.cpp
@@ -135,9 +135,13 @@ bool parse_scene_command(const char* json, ScenePayload& out_payload, std::strin
     return parse_scene_payload(json, out_payload, error_message);
 }
 
-bool parse_control_command(const char* json, ControlAction& out_action, std::string* error_message)
+bool parse_control_command(const char* json, ControlAction& out_action, std::string* out_mode,
+                           std::string* error_message)
 {
     out_action = ControlAction::None;
+    if (out_mode) {
+        out_mode->clear();
+    }
 
     if (!json) {
         set_error(error_message, "control command was null");
@@ -165,6 +169,17 @@ bool parse_control_command(const char* json, ControlAction& out_action, std::str
         out_action = ControlAction::ShowStatus;
         return true;
     }
+    if (cmd == "shipReceiptsSetMode") {
+        if (!doc["mode"].is<const char*>()) {
+            set_error(error_message, "shipReceiptsSetMode missing mode");
+            return false;
+        }
+        out_action = ControlAction::SetMode;
+        if (out_mode) {
+            *out_mode = doc["mode"].as<const char*>();
+        }
+        return true;
+    }
 
     set_error(error_message, "unknown ship receipts control command");
     return false;
diff --git a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
index c556e4d0..ee95dc20 100644
--- a/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
+++ b/firmware/main/apps/app_ship_receipts/ship_receipts_scene.h
@@ -13,6 +13,7 @@ enum class ControlAction {
     None = 0,
     ResumeDemo,
     ShowStatus,
+    SetMode,
 };
 
 struct ScenePayload {
@@ -37,6 +38,7 @@ struct ScenePayload {
 
 bool parse_scene_payload(const char* json, ScenePayload& out_payload, std::string* error_message = nullptr);
 bool parse_scene_command(const char* json, ScenePayload& out_payload, std::string* error_message = nullptr);
-bool parse_control_command(const char* json, ControlAction& out_action, std::string* error_message = nullptr);
+bool parse_control_command(const char* json, ControlAction& out_action, std::string* out_mode = nullptr,
+                           std::string* error_message = nullptr);
 
 }  // namespace ship_receipts
diff --git a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
index 69fbaacb..fceeeb41 100755
--- a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
+++ b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
@@ -25,6 +25,8 @@ def build_output(scene: dict, fmt: str) -> dict:
         return {"cmd": "shipReceiptsResumeDemo"}
     if fmt == "show-status":
         return {"cmd": "shipReceiptsShowStatus"}
+    if fmt == "set-mode":
+        return {"cmd": "shipReceiptsSetMode", "mode": scene.get("mode", "")}
     if fmt == "ws-text":
         return {
             "name": "ship-receipts",
@@ -59,7 +61,7 @@ def main() -> None:
     parser.add_argument("--scene", choices=sorted(SCENES.keys()), default="heike")
     parser.add_argument(
         "--format",
-        choices=["scene", "command", "ble-config", "ws-text", "transport-note", "metadata", "resume-demo", "show-status"],
+        choices=["scene", "command", "ble-config", "ws-text", "transport-note", "metadata", "resume-demo", "show-status", "set-mode"],
         default="command",
     )
     args = parser.parse_args()

From 4486239b6bdb08121e2f97f845503dc42047755c Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sat, 30 May 2026 14:06:30 -0500
Subject: [PATCH 15/24] feat: port ship receipts game modes

---
 .../main/apps/app_ship_receipts/README.md     | 37 +++++++++--------
 .../app_ship_receipts/app_ship_receipts.cpp   | 41 ++++++++++++++-----
 .../app_ship_receipts/app_ship_receipts.h     | 13 +++---
 .../examples/global_scene.json                | 22 ++++++++++
 .../examples/heike_scene.json                 | 23 -----------
 .../examples/local_scene.json                 | 23 +++++++++++
 .../examples/odyssey_scene.json               | 22 ----------
 .../examples/party_scene.json                 | 23 +++++++++++
 .../examples/ship_receipts_scene_command.json | 24 +++++------
 .../ship_receipts_set_mode_command.json       |  2 +-
 .../tools/emit_ship_receipts_scene.py         |  7 ++--
 11 files changed, 142 insertions(+), 95 deletions(-)
 create mode 100644 firmware/main/apps/app_ship_receipts/examples/global_scene.json
 delete mode 100644 firmware/main/apps/app_ship_receipts/examples/heike_scene.json
 create mode 100644 firmware/main/apps/app_ship_receipts/examples/local_scene.json
 delete mode 100644 firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
 create mode 100644 firmware/main/apps/app_ship_receipts/examples/party_scene.json

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index e5c488bf..28765070 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -26,7 +26,7 @@ This split gives us:
 ## What belongs here later
 
 - host scene packet consumers for Ship Receipts modes
-- Odyssey / Heike / future mode selection
+- local / global / party mode selection
 - app-local diagnostics relevant to Ship Receipts mode
 - branding and copy specific to this app
 - app-level use of generic core capabilities such as:
@@ -98,12 +98,12 @@ Accepted shapes:
 {
   "cmd": "shipReceiptsScene",
   "data": {
-    "title": "HEIKE",
-    "line": "Bell sounds. All things impermanent.",
-    "emotion": "sad",
-    "duration_ms": 4200,
-    "motion": {"yaw_angle": 180, "pitch_angle": 170, "speed": 320},
-    "led": {"r": 64, "g": 40, "b": 0},
+    "title": "LOCAL MODE",
+    "line": "No accounts. No auth. Just build and score receipts.",
+    "emotion": "happy",
+    "duration_ms": 3600,
+    "motion": {"yaw_angle": 140, "pitch_angle": 160, "speed": 320},
+    "led": {"r": 0, "g": 64, "b": 28},
     "play_notification": true
   }
 }
@@ -143,16 +143,16 @@ Mode selection command:
 ```json
 {
   "cmd": "shipReceiptsSetMode",
-  "mode": "heike"
+  "mode": "local"
 }
 ```
 
 That command explicitly jumps the built-in demo rotation to the first beat for
-the requested Ship Receipts mode.
+the requested Ship Receipts game mode.
 
 ## Current sequence states
 
-The app currently distinguishes between two app-local sequencing states:
+The app currently distinguishes between these app-local sequencing states:
 
 - `DemoRotation`
   - rotates through built-in sample beats
@@ -172,7 +172,7 @@ Ship Receipts sequencing policy down into StackChan core.
 The app-local scene payload currently understands:
 
 - `id` (optional scene identity for host/app orchestration)
-- `mode` (optional app mode such as `heike` or `odyssey`)
+- `mode` (optional app mode such as `local`, `global`, or `party`)
 - `title`
 - `line`
 - `speaker` (optional)
@@ -210,8 +210,9 @@ Current metadata behavior:
 
 Checked-in examples live here:
 
-- [examples/heike_scene.json](./examples/heike_scene.json)
-- [examples/odyssey_scene.json](./examples/odyssey_scene.json)
+- [examples/local_scene.json](./examples/local_scene.json)
+- [examples/global_scene.json](./examples/global_scene.json)
+- [examples/party_scene.json](./examples/party_scene.json)
 - [examples/ship_receipts_scene_command.json](./examples/ship_receipts_scene_command.json)
 - [examples/ship_receipts_resume_demo_command.json](./examples/ship_receipts_resume_demo_command.json)
 - [examples/ship_receipts_show_status_command.json](./examples/ship_receipts_show_status_command.json)
@@ -225,14 +226,14 @@ dependencies:
 Examples:
 
 ```bash
-python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format scene
-python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format command
-python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format ble-config
-python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format ws-text
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene local --format scene
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene local --format command
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene local --format ble-config
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene local --format ws-text
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format transport-note
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format resume-demo
 python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --format show-status
-python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene heike --format set-mode
+python3 firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py --scene local --format set-mode
 ```
 
 The `ws-text` format emits the `name` + `content` shape expected by the app's
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index fe33c79a..9afa1687 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -182,9 +182,13 @@ void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
 void AppShipReceipts::enterDemoRotation()
 {
     _sequence_state = SequenceState::DemoRotation;
-    _beat_index     = 0;
-    if (loadScene(_beat_index, _active_scene)) {
-        applyBeat(_active_scene);
+    if (!setDemoMode(_selected_demo_mode)) {
+        _beat_index = 0;
+        if (loadScene(_beat_index, _active_scene)) {
+            applyBeat(_active_scene);
+        }
+        mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation (fallback)");
+        return;
     }
     mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation");
 }
@@ -192,11 +196,27 @@ void AppShipReceipts::enterDemoRotation()
 void AppShipReceipts::resumeDemoRotation()
 {
     _sequence_state = SequenceState::DemoRotation;
-    _beat_index     = (_beat_index + 1) % _scene_json.size();
-    if (loadScene(_beat_index, _active_scene)) {
+    const auto start_index = _beat_index;
+    for (size_t offset = 1; offset <= _scene_json.size(); ++offset) {
+        const auto next_index = (start_index + offset) % _scene_json.size();
+        ship_receipts::ScenePayload candidate;
+        if (!loadScene(next_index, candidate)) {
+            continue;
+        }
+        if (!_selected_demo_mode.empty() && candidate.mode != _selected_demo_mode) {
+            continue;
+        }
+        _beat_index   = next_index;
+        _active_scene = std::move(candidate);
         applyBeat(_active_scene);
+        mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation (resumed)");
+        return;
     }
-    mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation (resumed)");
+    if (loadScene(start_index, _active_scene)) {
+        _beat_index = start_index;
+        applyBeat(_active_scene);
+    }
+    mclog::tagInfo(getAppInfo().name, "sequence state -> demo rotation (single-mode fallback)");
 }
 
 bool AppShipReceipts::setDemoMode(std::string_view mode)
@@ -208,6 +228,7 @@ bool AppShipReceipts::setDemoMode(std::string_view mode)
         }
         if (candidate.mode == mode) {
             _sequence_state = SequenceState::DemoRotation;
+            _selected_demo_mode = std::string(mode);
             _beat_index     = i;
             _active_scene   = std::move(candidate);
             applyBeat(_active_scene);
@@ -233,8 +254,9 @@ const char* AppShipReceipts::sequenceStateLabel() const
 
 std::string AppShipReceipts::statusSummary() const
 {
-    return fmt::format("state={} mode={} scene={}", sequenceStateLabel(),
+    return fmt::format("state={} mode={} selected={} scene={}", sequenceStateLabel(),
                        _active_scene.mode.empty() ? "-" : _active_scene.mode,
+                       _selected_demo_mode.empty() ? "-" : _selected_demo_mode,
                        _active_scene.scene_id.empty() ? "-" : _active_scene.scene_id);
 }
 
@@ -318,8 +340,5 @@ void AppShipReceipts::clearBeat()
 
 void AppShipReceipts::advanceBeat()
 {
-    _beat_index = (_beat_index + 1) % _scene_json.size();
-    if (loadScene(_beat_index, _active_scene)) {
-        applyBeat(_active_scene);
-    }
+    resumeDemoRotation();
 }
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index dec7553e..7ec093ab 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -35,11 +35,13 @@ class AppShipReceipts : public mooncake::AppAbility {
         LiveSticky,
     };
 
-    static constexpr std::array<const char*, 4> _scene_json{{
-        R"json({"id":"app-shell-card","mode":"ship-receipts-shell","title":"SHIP.RECEIPTS","line":"Host-driven scenes belong in the app layer.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3600,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":0,"b":0},"play_notification":false})json",
-        R"json({"id":"heike-avatar-1","mode":"heike","title":"HEIKE","speaker":"BIWA GUIDE","line":"Bell sounds. All things impermanent.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"sad","duration_ms":4200,"motion":{"yaw_angle":180,"pitch_angle":170,"speed":320},"led":{"r":64,"g":40,"b":0},"play_notification":true})json",
-        R"json({"id":"odyssey-card-1","mode":"odyssey","title":"ODYSSEY","line":"A card beat can become status plus speech.","presentation_type":"card","visual_template":"status_card","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":72},"play_notification":false})json",
-        R"json({"id":"app-boundary-avatar","mode":"ship-receipts-shell","title":"APP BOUNDARY","speaker":"STACKCHAN","line":"Motion, LEDs, and audio cues stay generic.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"doubtful","duration_ms":4200,"motion":{"yaw_angle":0,"pitch_angle":40,"speed":260},"led":{"r":36,"g":0,"b":56},"play_notification":true})json",
+    static constexpr std::array<const char*, 6> _scene_json{{
+        R"json({"id":"local-card-1","mode":"local","title":"LOCAL MODE","line":"Offline receipts, score loops, and streaks stay on-device.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":48,"b":22},"play_notification":false})json",
+        R"json({"id":"local-avatar-1","mode":"local","title":"LOCAL MODE","speaker":"BUILDER","line":"No accounts. No auth. Just build and score receipts.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":140,"pitch_angle":160,"speed":320},"led":{"r":0,"g":64,"b":28},"play_notification":true})json",
+        R"json({"id":"global-card-1","mode":"global","title":"GLOBAL MODE","line":"Proof envelopes can be exported for public verification.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":-80,"pitch_angle":90,"speed":300},"led":{"r":0,"g":28,"b":72},"play_notification":false})json",
+        R"json({"id":"global-avatar-1","mode":"global","title":"GLOBAL MODE","speaker":"LEDGER","line":"Verified receipts earn canonical reputation.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"doubtful","duration_ms":3800,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":96},"play_notification":true})json",
+        R"json({"id":"party-card-1","mode":"party","title":"PARTY MODE","line":"Track friends, rivals, and benchmarks beside your streaks.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":80,"pitch_angle":40,"speed":300},"led":{"r":72,"g":24,"b":72},"play_notification":false})json",
+        R"json({"id":"party-avatar-1","mode":"party","title":"PARTY MODE","speaker":"SCOUT","line":"Add GitHub users to the party and chase better proofs.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"happy","duration_ms":3800,"motion":{"yaw_angle":220,"pitch_angle":120,"speed":320},"led":{"r":96,"g":28,"b":96},"play_notification":true})json",
     }};
 
     bool loadScene(size_t index, ship_receipts::ScenePayload& out_scene);
@@ -60,5 +62,6 @@ class AppShipReceipts : public mooncake::AppAbility {
     uint32_t _beat_started_at = 0;
     size_t _beat_index        = 0;
     SequenceState _sequence_state = SequenceState::DemoRotation;
+    std::string _selected_demo_mode = "local";
     ship_receipts::ScenePayload _active_scene{};
 };
diff --git a/firmware/main/apps/app_ship_receipts/examples/global_scene.json b/firmware/main/apps/app_ship_receipts/examples/global_scene.json
new file mode 100644
index 00000000..b839ec0c
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/examples/global_scene.json
@@ -0,0 +1,22 @@
+{
+  "id": "global-card-1",
+  "mode": "global",
+  "title": "GLOBAL MODE",
+  "line": "Proof envelopes can be exported for public verification.",
+  "presentation_type": "card",
+  "visual_template": "status_card",
+  "emotion": "neutral",
+  "duration_ms": 3200,
+  "motion": {
+    "yaw_angle": -80,
+    "pitch_angle": 90,
+    "speed": 300
+  },
+  "led": {
+    "r": 0,
+    "g": 28,
+    "b": 72
+  },
+  "play_notification": false,
+  "sticky": false
+}
diff --git a/firmware/main/apps/app_ship_receipts/examples/heike_scene.json b/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
deleted file mode 100644
index 661945f7..00000000
--- a/firmware/main/apps/app_ship_receipts/examples/heike_scene.json
+++ /dev/null
@@ -1,23 +0,0 @@
-{
-  "id": "heike-avatar-1",
-  "mode": "heike",
-  "title": "HEIKE",
-  "speaker": "BIWA GUIDE",
-  "line": "Bell sounds. All things impermanent.",
-  "presentation_type": "avatar",
-  "visual_template": "avatar_beat",
-  "emotion": "sad",
-  "duration_ms": 4200,
-  "motion": {
-    "yaw_angle": 180,
-    "pitch_angle": 170,
-    "speed": 320
-  },
-  "led": {
-    "r": 64,
-    "g": 40,
-    "b": 0
-  },
-  "play_notification": true,
-  "sticky": false
-}
diff --git a/firmware/main/apps/app_ship_receipts/examples/local_scene.json b/firmware/main/apps/app_ship_receipts/examples/local_scene.json
new file mode 100644
index 00000000..41cb1062
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/examples/local_scene.json
@@ -0,0 +1,23 @@
+{
+  "id": "local-avatar-1",
+  "mode": "local",
+  "title": "LOCAL MODE",
+  "speaker": "BUILDER",
+  "line": "No accounts. No auth. Just build and score receipts.",
+  "presentation_type": "avatar",
+  "visual_template": "avatar_beat",
+  "emotion": "happy",
+  "duration_ms": 3600,
+  "motion": {
+    "yaw_angle": 140,
+    "pitch_angle": 160,
+    "speed": 320
+  },
+  "led": {
+    "r": 0,
+    "g": 64,
+    "b": 28
+  },
+  "play_notification": true,
+  "sticky": false
+}
diff --git a/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json b/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
deleted file mode 100644
index 029c47b8..00000000
--- a/firmware/main/apps/app_ship_receipts/examples/odyssey_scene.json
+++ /dev/null
@@ -1,22 +0,0 @@
-{
-  "id": "odyssey-card-1",
-  "mode": "odyssey",
-  "title": "ODYSSEY",
-  "line": "A card beat can become status plus speech.",
-  "presentation_type": "card",
-  "visual_template": "status_card",
-  "emotion": "happy",
-  "duration_ms": 3600,
-  "motion": {
-    "yaw_angle": -220,
-    "pitch_angle": 110,
-    "speed": 320
-  },
-  "led": {
-    "r": 0,
-    "g": 40,
-    "b": 72
-  },
-  "play_notification": false,
-  "sticky": false
-}
diff --git a/firmware/main/apps/app_ship_receipts/examples/party_scene.json b/firmware/main/apps/app_ship_receipts/examples/party_scene.json
new file mode 100644
index 00000000..f95aa46d
--- /dev/null
+++ b/firmware/main/apps/app_ship_receipts/examples/party_scene.json
@@ -0,0 +1,23 @@
+{
+  "id": "party-avatar-1",
+  "mode": "party",
+  "title": "PARTY MODE",
+  "speaker": "SCOUT",
+  "line": "Add GitHub users to the party and chase better proofs.",
+  "presentation_type": "avatar",
+  "visual_template": "avatar_beat",
+  "emotion": "happy",
+  "duration_ms": 3800,
+  "motion": {
+    "yaw_angle": 220,
+    "pitch_angle": 120,
+    "speed": 320
+  },
+  "led": {
+    "r": 96,
+    "g": 28,
+    "b": 96
+  },
+  "play_notification": true,
+  "sticky": false
+}
diff --git a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
index 4abf616b..e85fcad1 100644
--- a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
+++ b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_scene_command.json
@@ -1,24 +1,24 @@
 {
   "cmd": "shipReceiptsScene",
   "data": {
-    "id": "heike-avatar-1",
-    "mode": "heike",
-    "title": "HEIKE",
-    "speaker": "BIWA GUIDE",
-    "line": "Bell sounds. All things impermanent.",
+    "id": "local-avatar-1",
+    "mode": "local",
+    "title": "LOCAL MODE",
+    "speaker": "BUILDER",
+    "line": "No accounts. No auth. Just build and score receipts.",
     "presentation_type": "avatar",
     "visual_template": "avatar_beat",
-    "emotion": "sad",
-    "duration_ms": 4200,
+    "emotion": "happy",
+    "duration_ms": 3600,
     "motion": {
-      "yaw_angle": 180,
-      "pitch_angle": 170,
+      "yaw_angle": 140,
+      "pitch_angle": 160,
       "speed": 320
     },
     "led": {
-      "r": 64,
-      "g": 40,
-      "b": 0
+      "r": 0,
+      "g": 64,
+      "b": 28
     },
     "play_notification": true,
     "sticky": false
diff --git a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_set_mode_command.json b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_set_mode_command.json
index 579fee5d..1bc0ce53 100644
--- a/firmware/main/apps/app_ship_receipts/examples/ship_receipts_set_mode_command.json
+++ b/firmware/main/apps/app_ship_receipts/examples/ship_receipts_set_mode_command.json
@@ -1,4 +1,4 @@
 {
   "cmd": "shipReceiptsSetMode",
-  "mode": "heike"
+  "mode": "local"
 }
diff --git a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
index fceeeb41..67432410 100755
--- a/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
+++ b/firmware/main/apps/app_ship_receipts/tools/emit_ship_receipts_scene.py
@@ -7,8 +7,9 @@
 EXAMPLES = ROOT / "examples"
 
 SCENES = {
-    "heike": EXAMPLES / "heike_scene.json",
-    "odyssey": EXAMPLES / "odyssey_scene.json",
+    "local": EXAMPLES / "local_scene.json",
+    "global": EXAMPLES / "global_scene.json",
+    "party": EXAMPLES / "party_scene.json",
 }
 
 
@@ -58,7 +59,7 @@ def build_output(scene: dict, fmt: str) -> dict:
 
 def main() -> None:
     parser = argparse.ArgumentParser(description="Emit Ship Receipts app scene payloads for StackChan")
-    parser.add_argument("--scene", choices=sorted(SCENES.keys()), default="heike")
+    parser.add_argument("--scene", choices=sorted(SCENES.keys()), default="local")
     parser.add_argument(
         "--format",
         choices=["scene", "command", "ble-config", "ws-text", "transport-note", "metadata", "resume-demo", "show-status", "set-mode"],

From fc420fa490f01c3ecbee7ee98eefd1cbd2d22d26 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sat, 30 May 2026 16:10:16 -0500
Subject: [PATCH 16/24] feat: make ship receipts app state obvious

---
 .../app_ship_receipts/app_ship_receipts.cpp   | 27 +++++++++++++++----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 9afa1687..e32fa303 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -33,6 +33,22 @@ std::string buildSpeech(const ship_receipts::ScenePayload& beat)
     return fmt::format("{} says: {}", beat.speaker, beat.line);
 }
 
+std::string buildStatusLabel(const ship_receipts::ScenePayload& beat)
+{
+    if (beat.mode.empty()) {
+        return "SHIP.RECEIPTS";
+    }
+    return fmt::format("SHIP.RECEIPTS · {}", beat.mode);
+}
+
+std::string buildAppReadyMessage(std::string_view mode)
+{
+    if (mode.empty()) {
+        return "Ship Receipts app ready";
+    }
+    return fmt::format("Ship Receipts · {} mode", mode);
+}
+
 const char* resolveEmotion(const ship_receipts::ScenePayload& beat)
 {
     if (beat.presentation_type == "card") {
@@ -95,7 +111,7 @@ void AppShipReceipts::onOpen()
     });
 
     enterDemoRotation();
-    view::pop_a_toast("Ship Receipts demo shell ready", view::ToastType::Info, 1800);
+    view::pop_a_toast(buildAppReadyMessage(_selected_demo_mode), view::ToastType::Info, 1800);
 }
 
 void AppShipReceipts::onRunning()
@@ -161,14 +177,15 @@ void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
     auto speech   = buildSpeech(beat);
 
     if (display) {
-        display->SetStatus(beat.title.c_str());
+        auto status = buildStatusLabel(beat);
+        display->SetStatus(status.c_str());
         display->SetEmotion(resolveEmotion(beat));
         display->SetChatMessage("assistant", speech.c_str());
-        display->ShowNotification(beat.title.c_str(), 1400);
+        display->ShowNotification(status.c_str(), 1400);
     }
 
-    mclog::tagInfo(getAppInfo().name, "apply beat id='{}' mode='{}' template='{}' sticky={}", beat.scene_id,
-                   beat.mode, beat.visual_template, beat.sticky);
+    mclog::tagInfo(getAppInfo().name, "apply beat id='{}' mode='{}' template='{}' sticky={} status='{}'", beat.scene_id,
+                   beat.mode, beat.visual_template, beat.sticky, buildStatusLabel(beat));
 
     if (beat.play_notification) {
         hal_bridge::app_play_sound(OGG_NEW_NOTIFICATION);

From ac6b87020903ba1307f08f5958c43dd4a186e4d5 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sat, 30 May 2026 17:07:34 -0500
Subject: [PATCH 17/24] feat: deepen ship receipts mode rotations

---
 firmware/main/apps/app_ship_receipts/app_ship_receipts.h | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index 7ec093ab..3af9dd59 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -35,13 +35,16 @@ class AppShipReceipts : public mooncake::AppAbility {
         LiveSticky,
     };
 
-    static constexpr std::array<const char*, 6> _scene_json{{
+    static constexpr std::array<const char*, 9> _scene_json{{
         R"json({"id":"local-card-1","mode":"local","title":"LOCAL MODE","line":"Offline receipts, score loops, and streaks stay on-device.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":48,"b":22},"play_notification":false})json",
         R"json({"id":"local-avatar-1","mode":"local","title":"LOCAL MODE","speaker":"BUILDER","line":"No accounts. No auth. Just build and score receipts.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":140,"pitch_angle":160,"speed":320},"led":{"r":0,"g":64,"b":28},"play_notification":true})json",
+        R"json({"id":"local-card-2","mode":"local","title":"LOCAL MODE","line":"Only 6+ base-point receipts extend the streak.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":40,"pitch_angle":120,"speed":300},"led":{"r":20,"g":88,"b":32},"play_notification":false})json",
         R"json({"id":"global-card-1","mode":"global","title":"GLOBAL MODE","line":"Proof envelopes can be exported for public verification.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":-80,"pitch_angle":90,"speed":300},"led":{"r":0,"g":28,"b":72},"play_notification":false})json",
         R"json({"id":"global-avatar-1","mode":"global","title":"GLOBAL MODE","speaker":"LEDGER","line":"Verified receipts earn canonical reputation.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"doubtful","duration_ms":3800,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":96},"play_notification":true})json",
+        R"json({"id":"global-card-2","mode":"global","title":"GLOBAL MODE","line":"The server re-checks the proof. Local scores are only hints.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3400,"motion":{"yaw_angle":-140,"pitch_angle":130,"speed":300},"led":{"r":0,"g":56,"b":112},"play_notification":false})json",
         R"json({"id":"party-card-1","mode":"party","title":"PARTY MODE","line":"Track friends, rivals, and benchmarks beside your streaks.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":80,"pitch_angle":40,"speed":300},"led":{"r":72,"g":24,"b":72},"play_notification":false})json",
         R"json({"id":"party-avatar-1","mode":"party","title":"PARTY MODE","speaker":"SCOUT","line":"Add GitHub users to the party and chase better proofs.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"happy","duration_ms":3800,"motion":{"yaw_angle":220,"pitch_angle":120,"speed":320},"led":{"r":96,"g":28,"b":96},"play_notification":true})json",
+        R"json({"id":"party-card-2","mode":"party","title":"PARTY MODE","line":"Ranks break ties by streak first, then by join date.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3400,"motion":{"yaw_angle":120,"pitch_angle":90,"speed":300},"led":{"r":124,"g":52,"b":124},"play_notification":false})json",
     }};
 
     bool loadScene(size_t index, ship_receipts::ScenePayload& out_scene);

From 974f3a7d7a5b566bace5655521aa3f6705920819 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sun, 31 May 2026 06:40:47 -0500
Subject: [PATCH 18/24] feat: auto-open ship receipts on boot

---
 .../main/apps/app_launcher/app_launcher.cpp   | 24 ++++++++++++++++++-
 .../main/apps/app_launcher/app_launcher.h     |  2 ++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/firmware/main/apps/app_launcher/app_launcher.cpp b/firmware/main/apps/app_launcher/app_launcher.cpp
index e1e3d209..90775abe 100644
--- a/firmware/main/apps/app_launcher/app_launcher.cpp
+++ b/firmware/main/apps/app_launcher/app_launcher.cpp
@@ -70,11 +70,33 @@ void AppLauncher::onLauncherDestroy()
 void AppLauncher::create_launcher_view()
 {
     _view = std::make_unique<view::LauncherView>();
-    _view->init(getAppProps());
+    auto app_props = getAppProps();
+    _view->init(app_props);
     _view->onAppClicked = [&](int appID) {
         mclog::tagInfo(getAppInfo().name, "handle open app, app id: {}", appID);
         openApp(appID);
     };
+
+    maybe_open_initial_ship_receipts();
+}
+
+bool AppLauncher::maybe_open_initial_ship_receipts()
+{
+    if (_opened_initial_ship_receipts) {
+        return false;
+    }
+
+    for (const auto& props : getAppProps()) {
+        if (props.name == "SHIP.RECEIPTS") {
+            if (openApp(props.appID)) {
+                _opened_initial_ship_receipts = true;
+                mclog::tagInfo(getAppInfo().name, "auto-open ship receipts app, app id: {}", props.appID);
+                return true;
+            }
+        }
+    }
+
+    return false;
 }
 
 void AppLauncher::screensaver_update()
diff --git a/firmware/main/apps/app_launcher/app_launcher.h b/firmware/main/apps/app_launcher/app_launcher.h
index c62cca79..8ca5038e 100644
--- a/firmware/main/apps/app_launcher/app_launcher.h
+++ b/firmware/main/apps/app_launcher/app_launcher.h
@@ -25,7 +25,9 @@ class AppLauncher : public mooncake::templates::AppLauncherBase {
     std::unique_ptr<setup_workers::StartupWorker> _startup_worker;
     uint32_t _screensaver_timecount = 0;
     bool _startup_checked           = false;
+    bool _opened_initial_ship_receipts = false;
 
     void create_launcher_view();
     void screensaver_update();
+    bool maybe_open_initial_ship_receipts();
 };

From 7ea4de3bad0064da32bf2b4cf2db363ad7e7a714 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sun, 31 May 2026 06:41:12 -0500
Subject: [PATCH 19/24] fix: use app props info for auto-open

---
 firmware/main/apps/app_launcher/app_launcher.cpp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/firmware/main/apps/app_launcher/app_launcher.cpp b/firmware/main/apps/app_launcher/app_launcher.cpp
index 90775abe..5c223f27 100644
--- a/firmware/main/apps/app_launcher/app_launcher.cpp
+++ b/firmware/main/apps/app_launcher/app_launcher.cpp
@@ -87,7 +87,7 @@ bool AppLauncher::maybe_open_initial_ship_receipts()
     }
 
     for (const auto& props : getAppProps()) {
-        if (props.name == "SHIP.RECEIPTS") {
+        if (props.info.name == "SHIP.RECEIPTS") {
             if (openApp(props.appID)) {
                 _opened_initial_ship_receipts = true;
                 mclog::tagInfo(getAppInfo().name, "auto-open ship receipts app, app id: {}", props.appID);

From 83d9d6e998613e5395d3035d90b930b73eed944d Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sun, 31 May 2026 06:43:33 -0500
Subject: [PATCH 20/24] feat: bypass setup flow for ship receipts boot

---
 firmware/main/apps/app_launcher/app_launcher.cpp | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/firmware/main/apps/app_launcher/app_launcher.cpp b/firmware/main/apps/app_launcher/app_launcher.cpp
index 5c223f27..02eebc1e 100644
--- a/firmware/main/apps/app_launcher/app_launcher.cpp
+++ b/firmware/main/apps/app_launcher/app_launcher.cpp
@@ -26,12 +26,11 @@ void AppLauncher::onLauncherOpen()
 
     LvglLockGuard lock;
 
-    if (!_startup_checked && !GetHAL().isAppConfiged()) {
-        mclog::tagInfo(getAppInfo().name, "app not configured, start startup worker");
-        _startup_worker = std::make_unique<setup_workers::StartupWorker>();
-    } else {
-        create_launcher_view();
-    }
+    // For this fork, prefer entering SHIP.RECEIPTS directly instead of blocking
+    // on first-run setup flows like Wi-Fi scanning.
+    _startup_checked = true;
+    _startup_worker.reset();
+    create_launcher_view();
 }
 
 void AppLauncher::onLauncherRunning()

From 34c68af1ba08318f6096d1f30a14ff0444eb2792 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sun, 31 May 2026 06:48:19 -0500
Subject: [PATCH 21/24] fix: initialize ship receipts display ui before beats

---
 firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index e32fa303..bbea9f3a 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -95,9 +95,9 @@ void AppShipReceipts::onOpen()
         LvglLockGuard lock;
         loading_page.reset();
 
-        auto avatar = std::make_unique<avatar::DefaultAvatar>();
-        avatar->init(lv_screen_active());
-        GetStackChan().attachAvatar(std::move(avatar));
+        if (auto* display = Board::GetInstance().GetDisplay()) {
+            display->SetupUI();
+        }
 
         view::create_home_indicator([&]() { close(); }, 0x93C5FD, 0x0F172A);
         view::create_status_bar(0x93C5FD, 0x0F172A);

From 7fb08e0963584dceb376e01e1d9ebdf7dca15fb9 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sun, 31 May 2026 06:50:59 -0500
Subject: [PATCH 22/24] fix: disable crashing ship receipts cue audio

---
 firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index bbea9f3a..1e105284 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -188,7 +188,7 @@ void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
                    beat.mode, beat.visual_template, beat.sticky, buildStatusLabel(beat));
 
     if (beat.play_notification) {
-        hal_bridge::app_play_sound(OGG_NEW_NOTIFICATION);
+        mclog::tagInfo(getAppInfo().name, "skip notification audio for ship receipts beat '{}'", beat.scene_id);
     }
 
     GetHAL().showRgbColor(beat.led_r, beat.led_g, beat.led_b);

From 896113354131e1fc7a0b44c69e5c3b5a54ce17fa Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sun, 31 May 2026 07:58:49 -0500
Subject: [PATCH 23/24] refactor: calm ship receipts demo pacing

---
 .../main/apps/app_ship_receipts/README.md     | 14 +++++
 .../app_ship_receipts/app_ship_receipts.cpp   | 61 ++++++++++++++++++-
 2 files changed, 73 insertions(+), 2 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 28765070..5a560b62 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -35,6 +35,20 @@ This split gives us:
   - audio cue playback
   - transport-fed scene packets
 
+## Current demo pacing
+
+The built-in `local` / `global` / `party` demo beats now apply a small amount of
+app-local pacing policy before touching hardware:
+
+- `card` beats are quieter:
+  - head motion is re-centered and slowed down
+  - RGB output is dimmed
+- `avatar` beats are still expressive, but motion is clamped to a smaller
+  range than the raw authored payload
+
+This keeps the app readable on a desk and avoids making the built-in demo loop
+feel like a constant hardware burn-in test.
+
 ## What should stay out
 
 - generic servo transport code
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
index 1e105284..2dc90e63 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.cpp
@@ -13,13 +13,26 @@
 #include <mooncake_log.h>
 #include <stackchan/stackchan.h>
 #include <smooth_lvgl.hpp>
+#include <algorithm>
+#include <cmath>
 #include <string_view>
+#include <tuple>
 
 using namespace mooncake;
 using namespace stackchan;
 
 namespace {
 
+int clampValue(int value, int min_value, int max_value)
+{
+    return std::max(min_value, std::min(value, max_value));
+}
+
+uint8_t scaleColor(uint8_t value, float scale)
+{
+    return static_cast<uint8_t>(std::round(static_cast<float>(value) * scale));
+}
+
 std::string buildSpeech(const ship_receipts::ScenePayload& beat)
 {
     if (beat.speaker.empty()) {
@@ -56,6 +69,40 @@ const char* resolveEmotion(const ship_receipts::ScenePayload& beat)
     }
     return beat.emotion.c_str();
 }
+
+int resolveYawAngle(const ship_receipts::ScenePayload& beat)
+{
+    if (beat.presentation_type == "card") {
+        return clampValue(beat.yaw_angle / 3, -60, 60);
+    }
+    return clampValue(beat.yaw_angle, -180, 180);
+}
+
+int resolvePitchAngle(const ship_receipts::ScenePayload& beat)
+{
+    if (beat.presentation_type == "card") {
+        return clampValue(std::max(60, beat.pitch_angle / 2), 60, 140);
+    }
+    return clampValue(std::max(90, beat.pitch_angle), 90, 190);
+}
+
+int resolveMotionSpeed(const ship_receipts::ScenePayload& beat)
+{
+    if (beat.presentation_type == "card") {
+        return clampValue(beat.speed / 2, 120, 220);
+    }
+    return clampValue(beat.speed, 180, 320);
+}
+
+std::tuple<uint8_t, uint8_t, uint8_t> resolveLedColor(const ship_receipts::ScenePayload& beat)
+{
+    const auto scale = beat.presentation_type == "card" ? 0.28f : 0.45f;
+    return {
+        scaleColor(beat.led_r, scale),
+        scaleColor(beat.led_g, scale),
+        scaleColor(beat.led_b, scale),
+    };
+}
 }  // namespace
 
 AppShipReceipts::AppShipReceipts()
@@ -191,8 +238,18 @@ void AppShipReceipts::applyBeat(const ship_receipts::ScenePayload& beat)
         mclog::tagInfo(getAppInfo().name, "skip notification audio for ship receipts beat '{}'", beat.scene_id);
     }
 
-    GetHAL().showRgbColor(beat.led_r, beat.led_g, beat.led_b);
-    motion.moveWithSpeed(beat.yaw_angle, beat.pitch_angle, beat.speed);
+    const auto [led_r, led_g, led_b] = resolveLedColor(beat);
+    const auto yaw_angle = resolveYawAngle(beat);
+    const auto pitch_angle = resolvePitchAngle(beat);
+    const auto motion_speed = resolveMotionSpeed(beat);
+
+    mclog::tagInfo(getAppInfo().name,
+                   "resolved beat id='{}' motion=({}, {}, {}) led=({}, {}, {})",
+                   beat.scene_id, yaw_angle, pitch_angle, motion_speed,
+                   static_cast<int>(led_r), static_cast<int>(led_g), static_cast<int>(led_b));
+
+    GetHAL().showRgbColor(led_r, led_g, led_b);
+    motion.moveWithSpeed(yaw_angle, pitch_angle, motion_speed);
     _beat_started_at = GetHAL().millis();
 }
 

From db007a9fba953a7f2d9aa45a6e3f9a036e9efa96 Mon Sep 17 00:00:00 2001
From: John Malone <john.malone@gmail.com>
Date: Sun, 31 May 2026 12:14:56 -0500
Subject: [PATCH 24/24] feat: deepen ship receipts mode semantics

---
 .../main/apps/app_ship_receipts/README.md     | 15 +++++++++++++
 .../app_ship_receipts/app_ship_receipts.h     | 21 +++++++++++--------
 2 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/firmware/main/apps/app_ship_receipts/README.md b/firmware/main/apps/app_ship_receipts/README.md
index 5a560b62..59a8465d 100644
--- a/firmware/main/apps/app_ship_receipts/README.md
+++ b/firmware/main/apps/app_ship_receipts/README.md
@@ -208,6 +208,21 @@ Current rendering behavior:
   - forces a neutral face
   - treats speech as supporting card copy instead of character dialogue
 
+Current built-in mode coverage:
+
+- `local`
+  - offline single-player loop
+  - score, streak, and party growth stay on-device
+- `global`
+  - opt-in proof envelope export
+  - public verification and canonical reputation
+- `party`
+  - friendly comparison against party members and benchmarks
+  - local-first competition until someone exports a proof
+
+The built-in demo rotation now carries four beats per mode so the app can show
+more of each mode's actual semantics before it loops.
+
 Current metadata behavior:
 
 - `id`
diff --git a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
index 3af9dd59..66672b5a 100644
--- a/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
+++ b/firmware/main/apps/app_ship_receipts/app_ship_receipts.h
@@ -35,16 +35,19 @@ class AppShipReceipts : public mooncake::AppAbility {
         LiveSticky,
     };
 
-    static constexpr std::array<const char*, 9> _scene_json{{
-        R"json({"id":"local-card-1","mode":"local","title":"LOCAL MODE","line":"Offline receipts, score loops, and streaks stay on-device.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":48,"b":22},"play_notification":false})json",
-        R"json({"id":"local-avatar-1","mode":"local","title":"LOCAL MODE","speaker":"BUILDER","line":"No accounts. No auth. Just build and score receipts.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":140,"pitch_angle":160,"speed":320},"led":{"r":0,"g":64,"b":28},"play_notification":true})json",
-        R"json({"id":"local-card-2","mode":"local","title":"LOCAL MODE","line":"Only 6+ base-point receipts extend the streak.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":40,"pitch_angle":120,"speed":300},"led":{"r":20,"g":88,"b":32},"play_notification":false})json",
-        R"json({"id":"global-card-1","mode":"global","title":"GLOBAL MODE","line":"Proof envelopes can be exported for public verification.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":-80,"pitch_angle":90,"speed":300},"led":{"r":0,"g":28,"b":72},"play_notification":false})json",
-        R"json({"id":"global-avatar-1","mode":"global","title":"GLOBAL MODE","speaker":"LEDGER","line":"Verified receipts earn canonical reputation.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"doubtful","duration_ms":3800,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":96},"play_notification":true})json",
-        R"json({"id":"global-card-2","mode":"global","title":"GLOBAL MODE","line":"The server re-checks the proof. Local scores are only hints.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3400,"motion":{"yaw_angle":-140,"pitch_angle":130,"speed":300},"led":{"r":0,"g":56,"b":112},"play_notification":false})json",
+    static constexpr std::array<const char*, 12> _scene_json{{
+        R"json({"id":"local-card-1","mode":"local","title":"LOCAL MODE","line":"Everything works offline. No accounts, auth, or server calls.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":0,"pitch_angle":0,"speed":420},"led":{"r":0,"g":48,"b":22},"play_notification":false})json",
+        R"json({"id":"local-avatar-1","mode":"local","title":"LOCAL MODE","speaker":"BUILDER","line":"Ship work, create a receipt, and get immediate score feedback.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":140,"pitch_angle":160,"speed":320},"led":{"r":0,"g":64,"b":28},"play_notification":true})json",
+        R"json({"id":"local-card-2","mode":"local","title":"LOCAL MODE","line":"No score without proof. Empty receipts stay at zero.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":40,"pitch_angle":120,"speed":300},"led":{"r":20,"g":88,"b":32},"play_notification":false})json",
+        R"json({"id":"local-avatar-2","mode":"local","title":"LOCAL MODE","speaker":"STREAK","line":"Only 6-plus point receipts extend the streak and grow the party.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"sleepy","duration_ms":3600,"motion":{"yaw_angle":-100,"pitch_angle":150,"speed":280},"led":{"r":12,"g":72,"b":24},"play_notification":false})json",
+        R"json({"id":"global-card-1","mode":"global","title":"GLOBAL MODE","line":"Export a proof envelope only when you want public verification.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":-80,"pitch_angle":90,"speed":300},"led":{"r":0,"g":28,"b":72},"play_notification":false})json",
+        R"json({"id":"global-avatar-1","mode":"global","title":"GLOBAL MODE","speaker":"LEDGER","line":"Verified receipts earn canonical reputation, not just local score.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"doubtful","duration_ms":3800,"motion":{"yaw_angle":-220,"pitch_angle":110,"speed":320},"led":{"r":0,"g":40,"b":96},"play_notification":true})json",
+        R"json({"id":"global-card-2","mode":"global","title":"GLOBAL MODE","line":"The server re-checks the proof. Local hints never outrank verification.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3400,"motion":{"yaw_angle":-140,"pitch_angle":130,"speed":300},"led":{"r":0,"g":56,"b":112},"play_notification":false})json",
+        R"json({"id":"global-avatar-2","mode":"global","title":"GLOBAL MODE","speaker":"VERIFY","line":"Global badges and gold shields only appear after the pipeline passes.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"happy","duration_ms":3600,"motion":{"yaw_angle":-120,"pitch_angle":150,"speed":300},"led":{"r":0,"g":52,"b":132},"play_notification":false})json",
         R"json({"id":"party-card-1","mode":"party","title":"PARTY MODE","line":"Track friends, rivals, and benchmarks beside your streaks.","presentation_type":"card","visual_template":"title_card","emotion":"neutral","duration_ms":3200,"motion":{"yaw_angle":80,"pitch_angle":40,"speed":300},"led":{"r":72,"g":24,"b":72},"play_notification":false})json",
-        R"json({"id":"party-avatar-1","mode":"party","title":"PARTY MODE","speaker":"SCOUT","line":"Add GitHub users to the party and chase better proofs.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"happy","duration_ms":3800,"motion":{"yaw_angle":220,"pitch_angle":120,"speed":320},"led":{"r":96,"g":28,"b":96},"play_notification":true})json",
-        R"json({"id":"party-card-2","mode":"party","title":"PARTY MODE","line":"Ranks break ties by streak first, then by join date.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3400,"motion":{"yaw_angle":120,"pitch_angle":90,"speed":300},"led":{"r":124,"g":52,"b":124},"play_notification":false})json",
+        R"json({"id":"party-avatar-1","mode":"party","title":"PARTY MODE","speaker":"SCOUT","line":"Add GitHub users to the party and compare proof-first progress.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"happy","duration_ms":3800,"motion":{"yaw_angle":220,"pitch_angle":120,"speed":320},"led":{"r":96,"g":28,"b":96},"play_notification":true})json",
+        R"json({"id":"party-card-2","mode":"party","title":"PARTY MODE","line":"Friendly ranks break ties by streak first, then by join date.","presentation_type":"card","visual_template":"status_card","emotion":"neutral","duration_ms":3400,"motion":{"yaw_angle":120,"pitch_angle":90,"speed":300},"led":{"r":124,"g":52,"b":124},"play_notification":false})json",
+        R"json({"id":"party-avatar-2","mode":"party","title":"PARTY MODE","speaker":"PARTY","line":"Benchmarks stay local until someone chooses to export a proof.","presentation_type":"avatar","visual_template":"avatar_beat","emotion":"sleepy","duration_ms":3600,"motion":{"yaw_angle":120,"pitch_angle":140,"speed":280},"led":{"r":90,"g":36,"b":90},"play_notification":false})json",
     }};
 
     bool loadScene(size_t index, ship_receipts::ScenePayload& out_scene);