feat(instructions): hardcode MID pages with example-cue visual aids

Replace the plain-text instruction file with a hardcoded list of
InstructionPage entries. Split the combined circle/square explanations
into one-shape-per-page so each can render the cue it describes, and draw
the full example cue (shape + magnitude chord + dollar label) via
display.draw_cue so participants preview exactly what a real trial shows.

- Remove text/instructions_MID.txt and its _load_pages/file I/O
- Update docs/development.md file tree accordingly

Author: ericwang401

docs/development.md

@@ -138,7 +138,7 @@ mid-task-deterministic/
 │   ├── run_2.csv             # 54-trial sequence for run 2
 │   └── practice.csv          # 18-trial practice (one trial per condition)
 ├── text/
-│   └── instructions_MID.txt  # Instruction pages (one line per page)
+│   └── instructions_ratings.txt  # Cue-ratings instructions (MID task pages are hardcoded in task/instructions.py)
 ├── data/                     # Output directory (created at runtime)
 ├── tests/
 ├── docs/

src/mid_det/task/instructions.py

@@ -1,12 +1,15 @@
 """
-Instruction presentation: pages through text/instructions_MID.txt (one page per
-non-blank line) via the shared psyexp_core instruction pager, then waits for the
-start key. The task owns the pages and how each is drawn; the harness owns the
-flip + key-polling navigation loop.
+Instruction presentation: pages through a hardcoded list of instruction pages
+via the shared psyexp_core instruction pager, then waits for the start key.
+
+Each page is text plus an optional cue shape drawn beneath it as a visual aid,
+so the pages that describe CIRCLE / SQUARE cues also show the shape. The task
+owns the pages and how each is drawn; the harness owns the flip + key-polling
+navigation loop.
 """
 from __future__ import annotations
 
-from pathlib import Path
+from dataclasses import dataclass
 
 from psychopy import visual
 from psychopy.hardware import keyboard
@@ -15,20 +18,62 @@
 from rich.console import Console
 
 from mid_det import config
+from mid_det.task import display
+
+
+@dataclass(frozen=True)
+class InstructionPage:
+    """One instruction page: prompt text and an optional example cue as a visual aid.
+
+    ``cue`` is a ``(polarity, magnitude)`` pair drawn via ``display.draw_cue`` — the
+    full cue (shape + magnitude chord + dollar label), matching what participants
+    see on a real trial — or ``None`` for a text-only page.
+    """
+    text: str
+    cue: tuple[str, int] | None = None
+
 
-_PROJECT_ROOT = Path(__file__).resolve().parents[3]   # src/mid_det/task/ -> project root
-_TEXT_DIR = _PROJECT_ROOT / "text"
+# The circle/square explanations are split one-shape-per-page so each page can
+# show the cue it describes. An example cue is drawn with a representative
+# high ($5) magnitude so the chord (magnitude line) is clearly off-center.
+# Navigation / "press to continue" hints are drawn by the harness (instr_first),
+# so they are not repeated in the text here.
+_EXAMPLE_MAGNITUDE = 5
 
+_PAGES: list[InstructionPage] = [
+    InstructionPage(
+        "In this experiment you will respond as quickly as possible to earn "
+        "money. You will see a cue indicating how much money you can win or "
+        "avoid losing. After this cue, a triangle will appear. Hit a button as "
+        "fast as you can when the triangle appears to win."
+    ),
+    InstructionPage(
+        "Cues are either circles or squares. CIRCLE cues mean that you can EARN "
+        "that amount if you hit the target.",
+        cue=("gain", _EXAMPLE_MAGNITUDE),
+    ),
+    InstructionPage(
+        "SQUARE cues mean that you can AVOID LOSING that amount if you hit the "
+        "target.",
+        cue=("loss", _EXAMPLE_MAGNITUDE),
+    ),
+    InstructionPage(
+        "If you miss a CIRCLE cue, you will NOT GAIN the amount shown in the cue.",
+        cue=("gain", _EXAMPLE_MAGNITUDE),
+    ),
+    InstructionPage(
+        "If you miss a SQUARE cue, you will LOSE the amount shown in the cue.",
+        cue=("loss", _EXAMPLE_MAGNITUDE),
+    ),
+    InstructionPage("Please HOLD STILL while you are in the scanner."),
+]
 
-def _load_pages(path: Path) -> list[str]:
-    """Read an instruction text file into a list of pages (one non-blank line each)."""
-    pages: list[str] = []
-    with open(path) as f:
-        for line in f:
-            stripped = line.rstrip()
-            if stripped:
-                pages.append(stripped)
-    return pages
+# On cue pages the prompt is raised so text clears the cue drawn at screen center,
+# and the "press to continue" hint is lowered so it clears the dollar label drawn
+# just below the cue. Plain pages keep the hint at its default position.
+_PROMPT_Y_PLAIN = 0.1
+_PROMPT_Y_WITH_CUE = 0.3
+_HINT_Y_WITH_CUE = -0.35
 
 
 def display_instructions(
@@ -37,19 +82,28 @@ def display_instructions(
     kb: keyboard.Keyboard,
     rcon: Console,
 ) -> None:
-    """Display instructions from text/instructions_MID.txt one page at a time."""
-    pages = _load_pages(_TEXT_DIR / "instructions_MID.txt")
-    if not pages:
-        return
+    """Display the hardcoded instruction pages one at a time."""
+    default_hint_y = stimuli.instr_first.pos[1]
 
-    def _draw_page(page: str, _is_last: bool) -> None:
-        stimuli.instr_prompt.text = page
+    def _draw_page(page: InstructionPage, _is_last: bool) -> None:
+        stimuli.instr_prompt.pos = (
+            0,
+            _PROMPT_Y_WITH_CUE if page.cue else _PROMPT_Y_PLAIN,
+        )
+        stimuli.instr_prompt.text = page.text
         stimuli.instr_prompt.draw()
+        if page.cue:
+            polarity, magnitude = page.cue
+            display.draw_cue(stimuli, polarity, magnitude)
+        stimuli.instr_first.pos = (
+            0,
+            _HINT_Y_WITH_CUE if page.cue else default_hint_y,
+        )
         stimuli.instr_first.draw()
 
     core_instructions.page_through(
         win,
-        pages,
+        _PAGES,
         _draw_page,
         forward_keys=config.INSTRUCTION_KEYS["forward"],
         back_keys=config.INSTRUCTION_KEYS["back"],