tutorial: replace orientation text with a guided, unlosable first fight

First-ever game now hard-rails the player through a 3-turn lesson (deck draw vs bit draw, lanes, the bell, taking damage, then a comeback win by sacrificing an Intruder + a bit for a heavy Kernel) instead of 5 pages of text, then drops them into a read-only ls/pwd shell. Skippable with [esc]. BoardScreen gains a guided mode; Shell gains restrict_to(); app runs it once per installation.

scrypt/app.py

@@ -193,6 +193,28 @@ class ScryptApp(App):
         if not fxmod.reduced_motion() and not self.skip_menu:
             await self.push_screen_wait(NoiseScreen())
 
+    async def _tutorial(self) -> None:
+        """Onboarding by doing: a hard-railed first fight the player cannot
+        lose, then a look-but-don't-touch shell. Skippable ([esc] in the
+        fight). Replaces the old wall-of-text orientation."""
+        from scrypt.ui import tutorial as tut
+
+        state = tut.build_fight(self.content)
+        result = await self.push_screen_wait(
+            BoardScreen(
+                state, intro=tut.TUTORIAL_INTRO, presence=self.presence,
+                director=None, guided=tut.LESSON,
+            )
+        )
+        if result is not Result.PLAYER_WIN:
+            return  # the player skipped; drop straight into the real run
+        await self.push_screen_wait(
+            ShellScreen(
+                tut.build_shell(), [], deck_names=[],
+                motd=tut.TUTORIAL_MOTD, presence=self.presence,
+            )
+        )
+
     async def _lobby(self) -> None:
         from scrypt.ui import fx as fxmod
         from scrypt.ui.boot import BootScreen
@@ -225,12 +247,25 @@ class ScryptApp(App):
                         self.can_carve = False
                         self.run_worker(self._wake_backend())
                     continue
+                if choice == "::settings::":
+                    from scrypt.ui.settings import SettingsScreen
+
+                    if await self.push_screen_wait(SettingsScreen()):
+                        # New brain chosen: drop the old one (and its server)
+                        # and re-resolve from the freshly saved settings.
+                        if self._server is not None:
+                            self._server.stop()
+                            self._server = None
+                        self._backend = None
+                        self.voice = None
+                        self.backend_waking = True
+                        self.run_worker(self._wake_backend())
+                    continue
                 self.deck_id = choice
                 if not self.legacy.get("initiated"):
-                    # First game on this machine, ever: orientation.
-                    from scrypt.ui.tutorial import OrientationScreen
-
-                    await self.push_screen_wait(OrientationScreen())
+                    # First game on this machine, ever: a guided, unlosable
+                    # fight + a read-only shell, in place of a wall of text.
+                    await self._tutorial()
                     self.legacy["initiated"] = True
                     self._fresh_game = True
                     legacy_store.save(self.legacy)

scrypt/sandbox/shell.py

@@ -54,6 +54,13 @@ class Shell:
     def available(self) -> list[str]:
         return sorted(self.commands)
 
+    def restrict_to(self, names) -> None:
+        """Keep only these commands; drop the rest. Unlike revoke(), nothing
+        is marked 'sold' — the others simply were never here (the read-only
+        tutorial shell). help() and tab-completion then show only what's left."""
+        keep = set(names)
+        self.commands = {n: h for n, h in self.commands.items() if n in keep}
+
     def most_used(self, exclude: tuple[str, ...] = ("help", "man")) -> str | None:
         """The command the Warden wants: most-used, still owned, not trivial."""
         for name, _ in self.usage.most_common():

scrypt/ui/board.py

@@ -91,6 +91,7 @@ class BoardScreen(Screen):
         tutorial: bool = False,
         intro_moment: str | None = None,
         track=None,
+        guided: list[tuple[str, str]] | None = None,
     ):
         super().__init__()
         self.state = state
@@ -99,6 +100,11 @@ class BoardScreen(Screen):
         self.presence = presence  # WardenPresence or None (scripted lines only)
         self.director = director  # warden.director.Director or None
         self.tutorial = tutorial  # show contextual hints (first fight)
+        # Hard-railed lesson: ordered (key, hint). Only the head key advances;
+        # everything else is gently refused. Dismisses None when skipped.
+        self.guided = guided
+        self._lesson_pos = 0
+        self._nudged = False
         self.track = track  # Text: where this fight sits in the run
         self.mode = Mode.NORMAL
         self.selected = 0
@@ -417,6 +423,12 @@ class BoardScreen(Screen):
         return Text("")
 
     def _hint(self) -> str:
+        if self.guided is not None and self.state.phase is not Phase.OVER:
+            if self._lesson_pos >= len(self.guided):
+                return ""
+            prefix = "↳ not yet — " if self._nudged else ""
+            self._nudged = False
+            return prefix + self.guided[self._lesson_pos][1]
         if not self.tutorial or self.state.phase is Phase.OVER:
             return ""
         if self.state.phase is Phase.DRAW:
@@ -428,6 +440,8 @@ class BoardScreen(Screen):
             won = self.state.result is Result.PLAYER_WIN
             cycles = f"  +{self.state.overkill_cycles} cycles" if won else ""
             return f"the fight is over{cycles}   [any key] continue"
+        if self.guided is not None:
+            return "do as the floor says   ·   [?] help   ·   [esc] skip tutorial"
         if self.state.phase is Phase.DRAW:
             opts = []
             if self.state.can_draw_main:
@@ -463,6 +477,8 @@ class BoardScreen(Screen):
             if state.phase is Phase.OVER:
                 self.dismiss(state.result)
                 return
+            if self.guided is not None and not self._guided_allows(key):
+                return  # hard rails: only the lesson's next key gets through
             if key == "q":
                 self.dismiss(None)  # abandoned
                 return
@@ -497,6 +513,27 @@ class BoardScreen(Screen):
         self._prefetch_outcomes()
         self.refresh_all()
 
+    def _guided_allows(self, key: str) -> bool:
+        """Hard rails. [esc] skips the whole tutorial; [?] still opens help;
+        otherwise only the lesson's next key advances. A wrong key is refused
+        with a nudge, never a penalty."""
+        if key == "escape":
+            self.dismiss(None)  # skip the tutorial -> the real run begins
+            return False
+        if key == "question_mark":
+            from scrypt.ui.menu import HowToPlayScreen
+
+            self.app.push_screen(HowToPlayScreen())
+            return False
+        if self._lesson_pos >= len(self.guided):
+            return True  # lesson done; just waiting for the fight to end
+        if key == self.guided[self._lesson_pos][0]:
+            self._lesson_pos += 1
+            return True
+        self._nudged = True
+        self.refresh_all()
+        return False
+
     def _cycle_inspect(self) -> None:
         """[tab] walks the magnifier across the foe's row, then puts it down."""
         occupied = [i for i, c in enumerate(self.state.foe_row) if c is not None]

scrypt/ui/tutorial.py

@@ -1,173 +1,134 @@
-"""Orientation: shown once per installation, the first time a game begins.
-
-Five pages: who the Warden is, the way out, the table, the economy of
-death, and the world between fights. Skippable, never repeated (the
-`initiated` flag in legacy.json), and everything it teaches stays
-reachable afterwards — [?] in a fight, [h] on the menu.
+"""The tutorial: a guided, unlosable first fight + a read-only first shell.
+
+Shown once per installation, the first time a game begins (gated by the
+`initiated` flag in legacy.json). Gamers want to play, not read — so instead
+of pages of text we hand-rail the player through one short fight, then drop
+them into a look-but-don't-touch shell. Both are skippable ([esc] in the
+fight). Everything taught here stays reachable afterwards via [?] in a fight
+and [h] on the menu (HowToPlayScreen).
+
+The fight is a five-beat lesson with a deliberate emotional arc: the player
+draws, plays a body, and TAKES DAMAGE — the scale tips against them for two
+turns so they learn what losing feels like — then they draw a heavy card,
+SACRIFICE their Intruder and a bit to afford it, and swing back to the win.
+It teaches: the deck draw [d], the bit draw [s], lanes, the bell, sacrifice,
+and the shape of a comeback.
+
+This module owns only the SCENARIO. BoardScreen consumes `LESSON` in its
+`guided` mode and hard-rails to it.
 """
 
 from __future__ import annotations
 
-from rich import box
-from rich.panel import Panel
-from rich.text import Text
-from textual import events
-from textual.app import ComposeResult
-from textual.containers import Vertical
-from textual.screen import Screen
-from textual.widgets import Static
-
-TABLE_DIAGRAM = """\
-      ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
-      │queued│ │      │ │queued│ │      │   arriving next turn
-      └──────┘ └──────┘ └──────┘ └──────┘
-      ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
-      │ foe  │ │      │ │ foe  │ │      │   the Warden's row
-      └──────┘ └──────┘ └──────┘ └──────┘
-   ───── you ██ ·· ·· ·· ··  ⚖  ·· ·· ·· ·· ·· foe ─────
-      ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
-      │yours │ │      │ │yours │ │      │   your row
-      └──────┘ └──────┘ └──────┘ └──────┘
-        [1]      [2]      [3]      [4]
-"""
-
-PAGES: list[tuple[str, str]] = [
-    (
-        "WHERE YOU ARE",
-        """\
-You are a process. A small one, freshly spawned, inside a machine
-that belongs to something called the WARDEN.
-
-The Warden is not a script wearing a villain mask. It is a language
-model running on this computer. It watches what you type, remembers
-you between runs, rewrites encounters while you explore, and keeps
-files on everyone who has died here.
-
-It has noticed you. That is rarely good news.""",
-    ),
-    (
-        "THE WAY OUT",
-        """\
-Objective: escape the machine.
-
-A run is a short gauntlet — the path reads left to right:
-
-    ⚔ fight     $ shell     † altar     + draft
-
-Win every fight and the last door opens: you walk out with root.
-
-You have 2 ttys. Lose a fight and one burns — you retry the same
-fight. Lose both and you are reaped: the run ends, the Warden files
-a report on your corpse, and your next run inherits the wreckage.""",
-    ),
-    (
-        "THE TABLE",
-        TABLE_DIAGRAM
-        + """
-Your processes hit the lane across from them — or the Warden's face
-when that lane is empty. Face damage tips THE SCALE. Tip it +5 your
-way and you win the fight; let it reach −5 and you are reaped.
-
-[b] rings the bell to end your turn. Then everything attacks.""",
-    ),
-    (
-        "THE ECONOMY OF DEATH",
-        """\
-Each turn you draw: [d] from your deck, or [s] a bit.
-A bit is a free 0/1 process whose entire purpose is to die.
-
-♦ cards are paid in blood — mark processes you already control and
-they are killed to summon it. ⊙ cards cost core dumps: you bank one
-each time a process of yours dies. Death is your economy. Spend it.
-
-Your two piles stand at the right of the table. When a pile says
-EMPTY, there is no more drawing from it. Watch them.
-
-Select any card and its exact rules appear under your hand.
-[tab] does the same for the Warden's cards. No mystery mechanics.""",
-    ),
-    (
-        "BETWEEN FIGHTS",
-        """\
-After a fight you get a shell. It is small, it is fake, and it is
-the most honest part of this machine. `ls`, `cat`, `cd`, `grep`
-your way around — [tab] completes, [↑] recalls — some files pay
-cycles, some hide cards, and one is a schedule you really should
-do something about.
-
-The altar sells power. The price is always one of YOUR commands —
-whichever you lean on most. Sold means gone for the rest of the
-run, and the Warden notices every time you reach for it anyway.
-
-Hints will follow you through your first fight. [?] reopens the
-rules any time. The Warden is listening — `say` something if you
-must. It will not be kind about it.""",
-    ),
+from scrypt.engine.cards import Cost, CostType, make_card
+from scrypt.engine.combat import CombatState, Phase, ScriptedPlay
+from scrypt.sandbox.shell import Shell
+from scrypt.sandbox.vfs import VFS
+
+# A weak free body. Power 1 so it can never race the scale to the win on its
+# own — the win has to come from the sacrifice payoff.
+INTRUDER = make_card(
+    "intruder",
+    name="Intruder",
+    power=1,
+    health=2,
+    flavor="You. Unscheduled, unwelcome, and barely running.",
+    art="  ▞▚\n ▌><▐\n  ▚▞",
+)
+
+# The payoff: a heavy MEM card. Two 1-mem fodder (the Intruder + a bit) pay
+# its cost; eight power swings the scale from behind straight to the win.
+KERNEL = make_card(
+    "kernel",
+    name="Kernel",
+    power=8,
+    health=4,
+    cost=Cost(CostType.MEM, 2),
+    flavor="Worth more than everything you fed it. That was the point.",
+    art=" ╔═══╗\n ║ ⌗ ║\n ╚═══╝",
+)
+
+# The Warden's pressure: parked in the first lane, it strikes the player's
+# face for 2 every turn (the player is told to stand clear of it), so the
+# scale slides negative until the comeback.
+SENTINEL = make_card(
+    "sentinel",
+    name="Sentinel",
+    power=2,
+    health=5,
+    flavor="It does not advance. It does not need to.",
+    art=" ▟█████▙\n  █ ▼ █\n ▜█████▛",
+)
+
+TUTORIAL_INTRO = (
+    "A new process wakes in my machine. Small. Unscheduled. Let me teach you "
+    "how this ends. Do exactly as the floor tells you."
+)
+
+# The lesson: ordered (expected_key, on-screen hint). BoardScreen's guided
+# mode accepts ONLY the head key (plus [?] help, [esc] skip) and pops on a
+# match. Keys: d=draw deck, s=take a bit, enter=begin/confirm a play,
+# 1-4=lane (or, in sacrifice mode, a process to mark), b=ring the bell.
+LESSON: list[tuple[str, str]] = [
+    # Turn 1 — the deck draw, a body on the board, and your first damage.
+    ("d", "This is the draw phase. Press [d] to pull a process from your deck."),
+    ("enter", "That Intruder is in your hand. Press [enter] to play it."),
+    ("2", "Stand it in the second lane, clear of the Warden: press [2]."),
+    ("b", "Ring the bell — press [b]. You strike for 1… then the Warden strikes back."),
+    # Turn 2 — the bit draw: free fodder, and falling further behind.
+    ("s", "You took 2 to the face. Now press [s] to take a bit — free 0/1 fodder."),
+    ("enter", "Press [enter] to play the bit."),
+    ("3", "Set the bit down in the third lane: press [3]."),
+    ("b", "Ring the bell again: [b]. The scale slides against you — on purpose."),
+    # Turn 3 — sacrifice the weak for the strong, and swing to the win.
+    ("d", "You're losing. Draw your answer: press [d]."),
+    ("enter", "The Kernel costs 2♦ — paid by killing your own. Press [enter] to begin."),
+    ("2", "Mark the Intruder to be sacrificed: press [2].   (1 of 2♦)"),
+    ("3", "Mark the bit too: press [3].   (2 of 2♦)"),
+    ("enter", "Press [enter] to feed them both to the Kernel."),
+    ("4", "Summon the Kernel into the fourth lane: press [4]."),
+    ("b", "Ring the bell: [b]. Eight power lands — the scale tips to +5. You win."),
 ]
 
+TUTORIAL_MOTD = """\
+you survived the table. this is the shell — the floor of my machine.
+in here, for now, you may only look:
+  ls      list what is lying around       pwd     where you are standing
+  say <words>   speak to me               fight   go back to the table
+look around. type `fight` when you are ready to begin for real.
+"""
 
-class OrientationScreen(Screen):
-    """Dismisses with True when the player has seen (or skipped) it all."""
-
-    CSS = """
-    #orient { height: 1fr; align: center middle; }
-    #orient-page { width: 76; height: auto; }
-    #orient-prompt { height: 1; dock: bottom; background: $panel; content-align: center middle; }
-    """
-
-    def __init__(self) -> None:
-        super().__init__()
-        self.page = 0
-
-    def compose(self) -> ComposeResult:
-        with Vertical(id="orient"):
-            yield Static(id="orient-page")
-        yield Static(id="orient-prompt")
-
-    def on_mount(self) -> None:
-        self._show()
-
-    def _dots(self) -> Text:
-        from scrypt.ui import palette as pal
-
-        t = Text()
-        for i in range(len(PAGES)):
-            t.append("● " if i <= self.page else "○ ",
-                     style=pal.WARDEN if i == self.page else pal.GHOST)
-        return t
-
-    def _show(self) -> None:
-        from scrypt.ui import palette as pal
-
-        title, body = PAGES[self.page]
-        self.query_one("#orient-page", Static).update(
-            Panel(
-                Text(body, style=pal.FG),
-                box=box.HEAVY,
-                border_style=pal.BORDER_BRIGHT,
-                title=Text(f"⟪ orientation — {title} ⟫", style=f"bold {pal.WARDEN}"),
-                subtitle=self._dots(),
-                subtitle_align="center",
-                padding=(1, 3),
-            )
-        )
-        last = self.page == len(PAGES) - 1
-        prompt = (
-            "[enter] the Warden is waiting"
-            if last
-            else "[enter] next   [backspace] back   [s] skip orientation"
-        )
-        self.query_one("#orient-prompt", Static).update(Text(prompt))
 
-    def on_key(self, event: events.Key) -> None:
-        if event.key == "s":
-            self.dismiss(True)
-        elif event.key == "backspace" and self.page > 0:
-            self.page -= 1
-            self._show()
-        elif event.key in ("enter", "space", "right"):
-            if self.page == len(PAGES) - 1:
-                self.dismiss(True)
-            else:
-                self.page += 1
-                self._show()
+def build_fight(content) -> CombatState:
+    """The deterministic guided fight. The draws are taken under full control
+    so the hard-railed lesson is exact regardless of the opening shuffle:
+    [d] yields the Intruder then the Kernel; [s] yields bits. A Sentinel is
+    parked in the first lane (from the script) and hammers the player's face
+    until the Kernel arrives."""
+    bit = content.card("bit")
+    state = CombatState(
+        main_deck=[INTRUDER, INTRUDER, INTRUDER],
+        side_deck=[bit, bit, bit],
+        script=[[ScriptedPlay(lane=0, card=SENTINEL)]],
+        seed=7,
+    )
+    # Replace the auto-dealt opening hand with an empty hand + scripted piles,
+    # so every draw the lesson asks for is exactly what arrives.
+    state.hand = []
+    state._draw_pile = [INTRUDER, KERNEL]
+    state._side_pile = [bit, bit, bit]
+    state.events = []  # discard the opening-deal log; the fight starts clean
+    state.phase = Phase.DRAW
+    return state
+
+
+def build_shell() -> Shell:
+    """A throwaway read-only shell for the tutorial: ls + pwd only (say/fight
+    are shell-screen verbs). A few files to list; nothing to open yet."""
+    vfs = VFS()  # cwd defaults to /home/drifter
+    vfs.write("/home/drifter/readme", "the only file you were meant to find.")
+    vfs.write("/home/drifter/scale.log", "balance: 0. it never stays there.")
+    vfs.write("/home/drifter/.cell", "you are here. so am I.")
+    shell = Shell(vfs)
+    shell.restrict_to(("ls", "pwd", "help"))
+    return shell

tests/test_ui.py

@@ -117,6 +117,58 @@ async def test_abandon_exits_app():
     assert app.return_value is None
 
 
+async def test_settings_screen_saves_byo_api(monkeypatch, tmp_path):
+    """A player picks 'My own API endpoint', fills it in, Save persists it."""
+    from textual.widgets import Button, Input, RadioSet
+
+    from scrypt.inference import config
+    from scrypt.ui.settings import SettingsScreen
+
+    monkeypatch.setenv("SCRYPT_HOME", str(tmp_path))
+    result = []
+
+    class Host(App):
+        def on_mount(self):
+            self.push_screen(SettingsScreen(), result.append)
+
+    async with Host().run_test(size=(100, 44)) as pilot:
+        await pilot.pause()
+        scr = pilot.app.screen
+        scr.query_one("#mode", RadioSet).focus()
+        await pilot.click("#mode-api")
+        scr.query_one("#base", Input).value = "http://localhost:8080/v1"
+        scr.query_one("#key", Input).value = "sk-test"
+        scr.query_one("#model", Input).value = "warden"
+        await pilot.click("#save")
+        await pilot.pause()
+
+    assert result == [True]
+    saved = config.load()
+    assert saved["backend"] == "api" and saved["api_model"] == "warden"
+
+
+async def test_settings_screen_cancel_changes_nothing(monkeypatch, tmp_path):
+    from textual.app import App as _App
+
+    from scrypt.inference import config
+    from scrypt.ui.settings import SettingsScreen
+
+    monkeypatch.setenv("SCRYPT_HOME", str(tmp_path))
+    result = []
+
+    class Host(_App):
+        def on_mount(self):
+            self.push_screen(SettingsScreen(), result.append)
+
+    async with Host().run_test(size=(100, 44)) as pilot:
+        await pilot.pause()
+        await pilot.click("#cancel")
+        await pilot.pause()
+
+    assert result == [False]
+    assert not (tmp_path / "settings.json").exists()
+
+
 async def test_full_victorious_run_through_all_nodes(tmp_path, monkeypatch):
     """Win two empty-script fights; pass through shell, altar, and draft,
     then the victory lap: the root epilogue and the exfiltration pick."""
@@ -306,7 +358,6 @@ async def test_shell_is_haunted_and_answers_say():
 
 async def test_menu_flow_deck_select_and_howto(tmp_path, monkeypatch):
     from scrypt.ui.menu import HowToPlayScreen, MenuScreen
-    from scrypt.ui.tutorial import OrientationScreen
 
     monkeypatch.setenv("SCRYPT_HOME", str(tmp_path))  # a fresh installation
     app = ScryptApp(seed=42)  # menu NOT skipped
@@ -321,41 +372,83 @@ async def test_menu_flow_deck_select_and_howto(tmp_path, monkeypatch):
         await pilot.pause()
         await pilot.press("enter")  # begin with selected deck
         await pilot.pause()
-        # A first game ever passes through orientation before the table.
-        assert isinstance(app.screen, OrientationScreen)
-        await pilot.press("s")  # the impatient may skip
+        # A first game ever opens in the guided, hard-railed tutorial fight.
+        assert isinstance(app.screen, BoardScreen)
+        assert app.screen.guided is not None
+        # A wrong key is refused, not obeyed: the lesson cursor doesn't move.
+        await pilot.press("b")  # not the first step ([d])
+        await pilot.pause()
+        assert app.screen._lesson_pos == 0
+        await pilot.press("escape")  # the impatient may skip the tutorial
         await pilot.pause()
+        # Skipping drops them straight into the real run's first fight.
         assert isinstance(app.screen, BoardScreen)
+        assert app.screen.guided is None
         assert app.deck_id == "forkstorm"
-        assert app.screen.tutorial  # first fight teaches
+        assert app.screen.tutorial  # first real fight still shows hints
 
 
-async def test_orientation_runs_once_per_installation(tmp_path, monkeypatch):
+async def test_tutorial_plays_through_once_per_installation(tmp_path, monkeypatch):
     from scrypt.engine import legacy as legacy_store
-    from scrypt.ui.tutorial import PAGES, OrientationScreen
+    from scrypt.ui.shell import ShellScreen
+    from scrypt.ui.tutorial import LESSON
 
     monkeypatch.setenv("SCRYPT_HOME", str(tmp_path))
+    monkeypatch.setenv("SCRYPT_REDUCED_MOTION", "1")  # synchronous bell, no wipes
     app = ScryptApp(seed=1)
     async with app.run_test() as pilot:
         await pilot.pause()
         await pilot.press("enter")  # begin
         await pilot.pause()
-        assert isinstance(app.screen, OrientationScreen)
-        await pilot.press("backspace")  # can't back off the first page
-        assert app.screen.page == 0
-        for _ in range(len(PAGES)):  # read every page to the end
-            await pilot.press("enter")
+        assert isinstance(app.screen, BoardScreen) and app.screen.guided is not None
+        for key, _hint in LESSON:  # follow the rails to the forced win
+            await pilot.press(key)
+            await pilot.pause()
+        await pilot.press("enter")  # dismiss the won fight
         await pilot.pause()
-        assert isinstance(app.screen, BoardScreen)
+        # The won tutorial fight hands off to the read-only shell.
+        assert isinstance(app.screen, ShellScreen)
+        assert sorted(app.screen.shell.available()) == ["help", "ls", "pwd"]
+        app.screen.query_one("#shell-prompt").value = "fight"
+        await pilot.press("enter")
+        await pilot.pause()
+        # `fight` leaves the tutorial and the real run's first fight begins.
+        assert isinstance(app.screen, BoardScreen) and app.screen.guided is None
     assert legacy_store.load()["initiated"] is True
 
-    # Same installation, new game: straight to the table.
+    # Same installation, new game: no tutorial, straight to the table.
     again = ScryptApp(seed=2)
     async with again.run_test() as pilot:
         await pilot.pause()
         await pilot.press("enter")
         await pilot.pause()
-        assert isinstance(again.screen, BoardScreen)
+        assert isinstance(again.screen, BoardScreen) and again.screen.guided is None
+
+
+def test_tutorial_lesson_takes_damage_then_wins():
+    """The hard-railed lesson, played on the engine, must (a) put the player
+    behind so they see damage, then (b) reach a win via sacrifice — so the
+    rails can never strand a player in an unwinnable fight."""
+    from scrypt.data import load_content
+    from scrypt.engine.combat import Phase, Result
+    from scrypt.ui import tutorial as tut
+
+    state = tut.build_fight(load_content())
+    # Turn 1: deck draw, play the Intruder (lane 2), trade blows with the foe.
+    state.draw("main")
+    state.play(0, 1)
+    state.ring_bell()
+    # Turn 2: bit draw, set the bit down (lane 3), fall further behind.
+    state.draw("side")
+    state.play(0, 2)
+    state.ring_bell()
+    assert state.scale < 0  # the player has visibly taken damage
+    # Turn 3: draw the Kernel, sacrifice the Intruder + bit to afford it, win.
+    state.draw("main")
+    state.play(0, 3, sacrifices=(1, 2))
+    assert state.dumps == 2  # two of the player's own processes died for it
+    state.ring_bell()
+    assert state.phase is Phase.OVER and state.result is Result.PLAYER_WIN
 
 
 async def test_board_inspects_foes_and_opens_help():