How Tutorials Are Made

This page is for anyone editing or adding a tutorial, not for someone just taking one — see Using the tutorials for that.

Every tutorial is a plain YAML file under the playground app's app/tutorials/ directory. There's an editor for them, but it only exists for local development — the deployed playground.paramira.org is a static build with no server behind it, so /dev/tutorials is structurally unreachable there. You edit tutorials by running the playground locally.

The editor

With the playground running locally (pnpm dev in apps/playground), open http://localhost:3000/dev/tutorials. It lists every tutorial with Preview, Edit, and Delete, and a form for creating or editing one — every field below has a matching input there, so you rarely need to hand-edit the YAML directly.

The shape of a tutorial

id: discover-tree
title: Explore the family tree canvas
summary: A short description shown on the tutorials list.
app: iwacu              # top-level menu
category: Features      # second-level menu
directory: Tree         # third-level menu
order: 3                # lower shows first within its menu
depends: [community-and-protocols]   # soft gate — a warning, not enforced
setup: seed-tree         # optional "step 0" button
teardown: clear-tree     # optional, enabled once complete
steps:
  - title: Create a tree
    body: What the learner reads for this step.
    pane: iwacu           # shell | abantu | iwacu
    route: /               # the pane's own route, app-relative
    check: tree-exists      # see "Checks" below
    actions:
      - text: Start with Demo Tree   # spotlighted, in order

app / category / directory are free text — they only have to agree with what other tutorials already use, so the three-level menu on /tutorials stays coherent. The editor's own fields autocomplete from what's already out there.

Checks

A check is a name from a small, fixed list — not a scripting language, deliberately. Each one is a real function that reads the embedded app's actual state and returns yes or no:

Most of these work because the embedded apps are same-origin with the playground shell — the same trick that lets your identity carry across abantu, iwacu, and isoko in the real apps carries over here too, so a check can read an app's IndexedDB or its current URL directly, with no special hook built into that app for it. url-path and ui-text don't even need that: they just look at what's on screen, so they work for a step in any app without touching its internals at all.

Adding a genuinely new kind of check means adding one function to the shared list — after that, any tutorial can use it by name.

Actions — the spotlight

actions:
  - text: Start with Demo Tree     # matched against visible button/link text
  - selector: '[title="Save"]'      # or a CSS selector, for icon-only controls
    label: Save your script          # optional tooltip; defaults to text/selector

Multiple entries are spotlighted one at a time — the learner clicks the first for real, and the highlight moves itself to the next. It's a visual aid layered on top of check, never a substitute for it: nothing about clicking through a spotlight marks a step complete on its own.

Setup and teardown

setup and teardown are also names from a small fixed list, matching the same idea as checks but in reverse — instead of reading state, they write it, so a learner can jump into a tutorial without redoing every prerequisite by hand.

Where a real signed action is what the tutorial actually needs — joining a test community, adopting a protocol — setup performs the real thing, the same way the app itself would, rather than faking the end state. Local-only state (a tree, a saved script) is written directly. Teardown is the same idea in reverse: it undoes what setup or the tutorial's own steps left behind, and its button only becomes clickable once the tutorial is actually complete.