teach-me: Instructions file for Kiro

Ink Authoring Correctness

Guidance for writing ink narrative stories and lesson code fragments that are not just syntactically valid but produce correct output. The reference stories in ink-test-project/stories/ and the ink-godot lessons already follow these rules — this documents the standard and the tooling that enforces it.

The core principle

"Compiles + reaches END" ≠ "produces correct output." A story can compile cleanly, pass playthrough (reach an ending), survive subagent review, and still print the wrong text. Three bug classes (below) are invisible to structural validation — they were caught historically only by a human reading the output. The golden-transcript check (mise run ink:transcripts) is the mechanism that catches them automatically.

The three correctness rules

1. Test a knot's read count from OUTSIDE, never self-loop

A knot's read count reflects entry, not internal passes. A condition that tests the enclosing knot's own count inside a self-loop never advances:

// WRONG — {shop} counts entries; self-loop never increments it
=== shop ===
{shop == 1: First visit!|Welcome back.}
+ [Look around] -> shop      // re-enters via divert, but count is stuck

Two correct patterns:

• Hub-and-spoke — divert out to a hub, re-enter the counted knot via a fresh divert (read count advances on each fresh entry). This is what the reference stories use (well→village→well).
• Explicit VAR counter — ~ visits = visits + 1 on each pass, branch on the variable, not the read count.

2. Choices in re-enterable locations must be sticky (+) or have a fallback

A once-only choice (* [text]) in a knot the player can re-enter (via loop-back or tunnel) is exhausted on re-entry. Without a sticky choice or an unconditional gather to fall through to, the player is stranded ("ran out of content"):

= weapons
* "Show me your swords." -> weapons.shown   // once-only dialogue — fine
+ [Leave] -> market_square                  // STICKY fallback — keeps loop alive
- -> market_square                          // gather also catches fall-through