The Young Lady's Illustrated Primer

    *  .  .    *  . * .    *  .    *  .  .  *  .

____________ ________  ___ ___________
| ___ \ ___ \_   _|  \/  ||  ___| ___ \
| |_/ / |_/ / | | | .  . || |__ | |_/ /
|  __/|    /  | | | |\/| ||  __||    /
| |   | |\ \ _| |_| |  | || |___| |\ \
\_|   \_| \_|\___/\_|  |_/\____/\_| \_|

    *  .  .    *  . * .    *  .    *  .  .  *  .

"The book would be her guardian, her teacher, and her best friend. It would be everything she needed. Whenever she needed it." — Neal Stephenson, The Diamond Age

The cover is midnight blue, with tiny gold stars that sparkle when you tilt it. When you open it, a small glowing creature floats up from between the pages.

"Hello," it says. "My name is Puck. And this book — this book — is for you."

A terminal adventure for young learners. Nine chapters. One companion. A whole world to explore.

Tags: educational game for kids, learning game, children's educational app, learn to read, math for kids, coding for kids, history for kids, terminal game for children, Neal Stephenson Diamond Age

What's Inside

670+ challenges across 93+ zones. Every challenge is multiple-choice or fill-in-the-blank, designed for short focused sessions. Progress saves automatically.

Finding Your Starting Place

When you begin a new campaign, Puck will ask you a few short questions to find the best place to start. There are no wrong answers — just a gentle way to begin where things are interesting, not too easy and not too hard.

You can also:

• Start at the beginning (Chapter 1: The Letter Garden)
• Jump to any chapter directly from the Chapter Map
• Play individual chapters as standalone adventures

Install

The easy way (recommended)

Mac / Linux:

pip install primer-quest

Windows — open PowerShell and run:

pip install primer-quest

If primer is not found after install: Open a new terminal window. If still missing, run python -m primer_game.main as a fallback.

Best experience on Windows: Use Windows Terminal (free, Microsoft Store). The default cmd.exe may display characters incorrectly.

One-liner installer (no pip? start here)

Mac / Linux:

curl -sSL https://raw.githubusercontent.com/thorski1/primer/main/install.sh | bash

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/thorski1/primer/main/install.ps1 | iex"

Then open a new terminal and run primer.

Auto-updates

The Primer checks for updates automatically at startup. When Puck has something new for you, you'll see:

╭──────────────────────────────╮
│      SOFTWARE UPDATE         │
│                              │
│  Update available!           │
│  Installed : v1.0.0          │
│  Latest    : v1.1.0          │
╰──────────────────────────────╯
  Install update now? [y/N]

Type y and the game updates and restarts itself.

Running

Gameplay

Puck introduces each topic through a short story, then presents challenges:

• Multiple Choice — read the question, type A / B / C / D
• Fill in the Blank — type the missing word or number

  Puck: [h] Hint  [b] Bookmark  [?] Help  [s] Skip  [q] Menu

Puck offers hints when you're stuck. Every wrong answer is just a step toward the right one.

Features

For Parents

• Each zone takes 5-15 minutes — designed for short, focused sessions
• Progress saves automatically between sessions
• The game works independently or as a shared reading experience — especially for younger children
• A placement quiz at the start finds the right chapter for each child
• All content is age-appropriate and celebrates curiosity, kindness, and growth
• The Primer is designed for girls but welcomes every curious reader

Requirements

• Python 3.10+
• A terminal (Terminal.app, iTerm2, Windows Terminal)
• 80+ column width recommended

Built On

Quest Engine — a pluggable terminal RPG framework.

Inspired by the Primer from Neal Stephenson's The Diamond Age.