pytorial 0.1__tar.gz

pytorial-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Daniel Bosk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytorial-0.1/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: pytorial
+Version: 0.1
+Summary: Interactive command-line tutorials with PTY-backed steps
+License-Expression: MIT
+License-File: LICENSE
+Author: Daniel Bosk
+Author-email: daniel@bosk.se
+Maintainer: Daniel Bosk
+Maintainer-email: dbosk@kth.se
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Education
+Requires-Dist: PyYAML (>=6)
+Requires-Dist: platformdirs (>=4)
+Requires-Dist: rich (>=12.3.0)
+Requires-Dist: typer (>=0.9.0)
+Project-URL: Bug Tracker, https://github.com/dbosk/tutorial/issues
+Project-URL: Repository, https://github.com/dbosk/tutorial
+Description-Content-Type: text/markdown
+
+# tutorial
+
+A Python library for interactive command-line tutorials.
+
+## Install
+
+```
+pipx install tutorial
+# or
+uv tool install tutorial
+```
+
+To run from a clone instead of an installed copy, see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Usage
+
+The package ships with three built-in tutorials. The first one is a
+self-guided tour of the tool itself:
+
+```
+tutorial run using-tutorials
+```
+
+Companion tours: `tutorial run shell-basics` (shell and editor skills)
+and `tutorial run writing-tutorials` (authoring tutorials of your own).
+
+### Discover what's available
+
+```
+tutorial list
+```
+
+Pipe the same command into a script to get tab-separated rows instead
+of the rich table.
+
+### Run or resume
+
+```
+tutorial run <id>              # start or resume saved progress
+tutorial run --restart <id>    # discard saved progress and start over
+```
+
+### Review past runs
+
+```
+tutorial review <id>
+tutorial review <id> --step 2
+tutorial review <id> --run-id <run-id>
+```
+
+### Trust author-supplied shell checks
+
+```
+tutorial run --allow-shell-checks <id>
+```
+
+A tutorial step may declare a `check_command` that runs in your shell
+to validate the step. This validation is opt-in: pass
+`--allow-shell-checks` only when you trust the tutorial author.
+
+## Writing tutorials
+
+Take the interactive walkthrough first:
+
+```
+tutorial run writing-tutorials
+```
+
+### File format
+
+A tutorial is a single Markdown file beginning with YAML front matter:
+
+````markdown
+---
+id: my-tutorial
+title: My Tutorial
+summary: One-line description shown by `tutorial list`.
+---
+
+# First step
+
+```tutorial-step
+required_patterns:
+  - some-command
+hint: Try running `some-command`.
+```
+
+Step body in Markdown.
+````
+
+- Required front-matter fields: `id`, `title`, `summary`.
+- Each top-level `# Heading` becomes one step.
+- A step may begin with a fenced `tutorial-step` YAML block. Recognised
+  fields are `required_patterns`, `check_command`, `hint`, `edit_file`,
+  `kind`, `options`, and `answers`.
+- Without `kind` or `edit_file`, a step opens an interactive shell.
+- `edit_file` opens a workspace-relative file in `$EDITOR`, falling
+  back to `vim`, `vi`, or `nano` when `$EDITOR` is unset.
+- `kind: input`, `kind: single_select`, and `kind: multi_select` prompt
+  directly in the CLI instead of opening a shell or editor. `input`
+  answers use the same string-or-`{mode, pattern}` format as
+  `required_patterns`; select questions use literal option text in
+  `options` and `answers`.
+- `check_command` only runs when the reader passes
+  `--allow-shell-checks`.
+
+### Share and install
+
+Install a tutorial Markdown file or URL into the user's tutorial
+directory:
+
+```
+tutorial install path/to/tutorial.md
+tutorial install https://example.com/tutorial.md
+tutorial install --force path/to/tutorial.md
+```
+
+Use `--force` to overwrite an installed tutorial with the same `id`.
+The standalone CLI auto-loads installed tutorials alongside the
+built-ins.
+
+### Load ad hoc
+
+To use a tutorial without installing it, point at the file or directory
+on the command line:
+
+```
+tutorial list --tutorial-path some/dir
+tutorial run --tutorial-path some/dir <id>
+```
+
+`--tutorial-path` may be repeated and is appended after the built-ins.
+
+## Embedding the CLI
+
+The package can be mounted as a subcommand inside another Typer or
+argparse application via `add_typer_subcommand` and
+`add_argparse_subcommand` in `src/tutorial/cli.py`. Embedded hosts
+prepend the `using-tutorials` lesson before host-specific tutorials, do
+not load the user's installed tutorial directory, and hide the
+standalone-only `install` command.
+
+## Contributing
+
+For the literate sources, the `make` build, and the repo layout, see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+

pytorial-0.1/README.md

@@ -0,0 +1,147 @@
+# tutorial
+
+A Python library for interactive command-line tutorials.
+
+## Install
+
+```
+pipx install tutorial
+# or
+uv tool install tutorial
+```
+
+To run from a clone instead of an installed copy, see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Usage
+
+The package ships with three built-in tutorials. The first one is a
+self-guided tour of the tool itself:
+
+```
+tutorial run using-tutorials
+```
+
+Companion tours: `tutorial run shell-basics` (shell and editor skills)
+and `tutorial run writing-tutorials` (authoring tutorials of your own).
+
+### Discover what's available
+
+```
+tutorial list
+```
+
+Pipe the same command into a script to get tab-separated rows instead
+of the rich table.
+
+### Run or resume
+
+```
+tutorial run <id>              # start or resume saved progress
+tutorial run --restart <id>    # discard saved progress and start over
+```
+
+### Review past runs
+
+```
+tutorial review <id>
+tutorial review <id> --step 2
+tutorial review <id> --run-id <run-id>
+```
+
+### Trust author-supplied shell checks
+
+```
+tutorial run --allow-shell-checks <id>
+```
+
+A tutorial step may declare a `check_command` that runs in your shell
+to validate the step. This validation is opt-in: pass
+`--allow-shell-checks` only when you trust the tutorial author.
+
+## Writing tutorials
+
+Take the interactive walkthrough first:
+
+```
+tutorial run writing-tutorials
+```
+
+### File format
+
+A tutorial is a single Markdown file beginning with YAML front matter:
+
+````markdown
+---
+id: my-tutorial
+title: My Tutorial
+summary: One-line description shown by `tutorial list`.
+---
+
+# First step
+
+```tutorial-step
+required_patterns:
+  - some-command
+hint: Try running `some-command`.
+```
+
+Step body in Markdown.
+````
+
+- Required front-matter fields: `id`, `title`, `summary`.
+- Each top-level `# Heading` becomes one step.
+- A step may begin with a fenced `tutorial-step` YAML block. Recognised
+  fields are `required_patterns`, `check_command`, `hint`, `edit_file`,
+  `kind`, `options`, and `answers`.
+- Without `kind` or `edit_file`, a step opens an interactive shell.
+- `edit_file` opens a workspace-relative file in `$EDITOR`, falling
+  back to `vim`, `vi`, or `nano` when `$EDITOR` is unset.
+- `kind: input`, `kind: single_select`, and `kind: multi_select` prompt
+  directly in the CLI instead of opening a shell or editor. `input`
+  answers use the same string-or-`{mode, pattern}` format as
+  `required_patterns`; select questions use literal option text in
+  `options` and `answers`.
+- `check_command` only runs when the reader passes
+  `--allow-shell-checks`.
+
+### Share and install
+
+Install a tutorial Markdown file or URL into the user's tutorial
+directory:
+
+```
+tutorial install path/to/tutorial.md
+tutorial install https://example.com/tutorial.md
+tutorial install --force path/to/tutorial.md
+```
+
+Use `--force` to overwrite an installed tutorial with the same `id`.
+The standalone CLI auto-loads installed tutorials alongside the
+built-ins.
+
+### Load ad hoc
+
+To use a tutorial without installing it, point at the file or directory
+on the command line:
+
+```
+tutorial list --tutorial-path some/dir
+tutorial run --tutorial-path some/dir <id>
+```
+
+`--tutorial-path` may be repeated and is appended after the built-ins.
+
+## Embedding the CLI
+
+The package can be mounted as a subcommand inside another Typer or
+argparse application via `add_typer_subcommand` and
+`add_argparse_subcommand` in `src/tutorial/cli.py`. Embedded hosts
+prepend the `using-tutorials` lesson before host-specific tutorials, do
+not load the user's installed tutorial directory, and hide the
+standalone-only `install` command.
+
+## Contributing
+
+For the literate sources, the `make` build, and the repo layout, see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).

pytorial-0.1/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "pytorial"
+version = "0.1"
+description = "Interactive command-line tutorials with PTY-backed steps"
+license = "MIT"
+readme = "README.md"
+authors = [
+  {name = "Daniel Bosk", email = "daniel@bosk.se"}
+]
+maintainers = [
+  {name = "Daniel Bosk", email = "dbosk@kth.se"}
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX :: Linux",
+  "Intended Audience :: Education",
+  "Topic :: Education"
+]
+requires-python = ">=3.10"
+dependencies = [
+  "platformdirs>=4",
+  "PyYAML>=6",
+  "rich>=12.3.0",
+  "typer>=0.9.0"
+]
+
+[project.scripts]
+tutorial = "tutorial.cli:app"
+pytorial = "tutorial.cli:app"
+
+[project.urls]
+repository = "https://github.com/dbosk/tutorial"
+"Bug Tracker" = "https://github.com/dbosk/tutorial/issues"
+
+[tool.poetry]
+packages = [{include = "tutorial", from = "src"}]
+include = [
+  {path = "src/**/*.py", format = "wheel"},
+  {path = "src/tutorial/tutorials/*.md"},
+]
+exclude = [
+  "src/tutorial/.gitignore",
+  "src/tutorial/Makefile",
+  "src/tutorial/*.nw",
+  "src/tutorial/*.tex",
+  "src/tutorial/ltxobj",
+]
+
+[tool.black]
+target-version = ["py310"]
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+  "pytest>=7.4"
+]

pytorial-0.1/src/tutorial/tutorials/shell-basics.md

@@ -0,0 +1,101 @@
+---
+id: shell-basics
+title: Shell Basics
+summary: Use directories, files, paths, and an editor in the workspace.
+---
+
+# Inspect the workspace
+
+```tutorial-step
+required_patterns:
+  - pwd
+  - ls
+hint: The shell starts in the tutorial workspace.
+```
+
+Run `pwd` and `ls`.
+
+Each tutorial run gets its own workspace. These commands show where your
+files for this run will live.
+
+# Create a directory
+
+```tutorial-step
+required_patterns:
+  - mkdir notes
+  - ls
+  - notes
+hint: Create a directory called `notes`, then list the workspace again.
+```
+
+Create a directory named `notes`, then run `ls` again.
+
+The contrast here is between the workspace before and after one directory
+is added.
+
+# Create a file in that directory
+
+```tutorial-step
+required_patterns:
+  - touch notes/todo.md
+  - ls notes
+  - todo.md
+hint: Use `touch` with the nested path `notes/todo.md`.
+```
+
+Create `notes/todo.md`, then run `ls notes`.
+
+Keep the same path stem `notes` while changing only what you create:
+first a directory, then a file inside it.
+
+# Edit the file
+
+```tutorial-step
+edit_file: notes/todo.md
+required_patterns:
+  - tutorial authoring
+  - remember this path
+```
+
+Open `notes/todo.md` in your editor and add two short lines:
+
+- `tutorial authoring`
+- `remember this path`
+
+Save the file and quit the editor.
+
+The path stays the same, but the interaction changes from shell commands
+to an editor-backed step.
+
+# Review the directory and the file
+
+```tutorial-step
+required_patterns:
+  - ls notes
+  - todo.md
+  - cat notes/todo.md
+  - tutorial authoring
+hint: First list the directory, then display the file.
+```
+
+Run `ls notes` and `cat notes/todo.md`.
+
+This contrasts two related views: listing a directory tells you which
+files exist, while `cat` shows what one file contains.
+
+# Generalise the pattern for tutorial files
+
+```tutorial-step
+required_patterns:
+  - mkdir my-tutorials
+  - touch my-tutorials/demo.md
+  - ls my-tutorials
+  - demo.md
+hint: Repeat the same directory-and-file pattern with new names.
+```
+
+Create a directory named `my-tutorials`, create
+`my-tutorials/demo.md`, then run `ls my-tutorials`.
+
+Now the names vary, but the path pattern `directory/file.md` stays the
+same. That is the pattern the tutorial-authoring lesson will build on.

pytorial-0.1/src/tutorial/tutorials/using-tutorials.md

@@ -0,0 +1,212 @@
+---
+id: using-tutorials
+title: Using Tutorials
+summary: Learn how list, run, question prompts, and review fit together.
+---
+
+# List the available tutorials
+
+```tutorial-step
+required_patterns:
+  - tutorial list
+  - using-tutorials
+  - shell-basics
+  - writing-tutorials
+hint: Run `tutorial list`.
+```
+
+Run `tutorial list`.
+
+In a terminal, `tutorial list` renders a readable table. When the same
+command is piped into a script, it switches to tab-separated rows.
+
+Its main job is to show which tutorials are available and how much
+progress is already saved for each one.
+
+# Start another tutorial
+
+```tutorial-step
+required_patterns:
+  - tutorial run --restart shell-basics
+  - "shell-basics $"
+  - "Step not complete yet: Inspect the workspace"
+hint: Start `shell-basics`, then leave its first shell with `exit`.
+```
+
+Run `tutorial run --restart shell-basics`.
+
+The `run` command starts or resumes saved work. We use `--restart` here so
+this step behaves the same way even if you have already finished
+`shell-basics` before. `--restart` discards every saved transcript for that
+tutorial, not just the step you are about to revisit.
+
+Because this lesson is already running, the nested shell prompt changes to
+`shell-basics $ ` so you can tell which tutorial owns the current shell.
+
+For this step:
+
+1. Run `tutorial run --restart shell-basics`.
+2. When the nested shell opens, type `exit`.
+3. After the nested command reports that the step is not complete yet,
+   exit this outer shell too.
+
+# Retry a shell step
+
+```tutorial-step
+required_patterns:
+  - "using-tutorials $"
+  - pwd
+  - ls
+hint: First exit after `pwd`, then choose `try again` and run both commands.
+```
+
+Now return to this tutorial's own shell.
+
+To feel how step validation works, try this step in two rounds:
+
+1. First run only `pwd`, then exit the shell.
+2. The tutorial should say the step is not complete yet.
+3. Choose `try again`, run both `pwd` and `ls`, then exit again.
+
+Only the latest recorded attempt counts. If you leave now and come back
+later, `tutorial run using-tutorials` resumes from the first unfinished
+step unless you restart it.
+
+# Capture the workflow in a file
+
+```tutorial-step
+edit_file: tutorial-commands.txt
+required_patterns:
+  - tutorial list discovers tutorials
+  - tutorial run starts or resumes one
+  - tutorial review shows saved transcripts
+```
+
+Open `tutorial-commands.txt` in your editor and add these three lines:
+
+- `tutorial list discovers tutorials`
+- `tutorial run starts or resumes one`
+- `tutorial review shows saved transcripts`
+
+Save the file and quit the editor.
+
+This contrasts a shell step with an editor step while keeping the same
+validation idea: the tutorial only checks what was recorded after you
+finish the step.
+
+# Answer a one-line question
+
+```tutorial-step
+kind: input
+answers:
+  - mode: regex
+    pattern: ^tutorial\s+review\s+using-tutorials(?:\s+)?$
+hint: Type the full review command for this tutorial.
+```
+
+Type the exact command that reviews this tutorial:
+`tutorial review using-tutorials`.
+
+This is the smallest question step. The tutorial asks for one line of
+text, records it immediately, and validates it without opening a shell.
+
+# Pick the command that starts work
+
+```tutorial-step
+kind: single_select
+options:
+  - tutorial list
+  - tutorial run
+  - tutorial review
+answers:
+  - tutorial run
+```
+
+Choose the command that starts or resumes one tutorial.
+
+Single-select questions show numbered options. You can answer with the
+number or with the full option text.
+
+# Pick every read-only tutorial command
+
+```tutorial-step
+kind: multi_select
+options:
+  - tutorial list
+  - tutorial run
+  - tutorial review
+  - tutorial install
+answers:
+  - tutorial list
+  - tutorial review
+hint: Choose the commands that only read tutorial definitions or saved state.
+```
+
+Choose every tutorial command here that reads existing information without
+starting a run or installing anything.
+
+Multi-select questions also use literal option text. The learner may pick
+the correct options in any order, but the tutorial still stores the
+authored answer list.
+
+# Review the saved run
+
+```tutorial-step
+required_patterns:
+  - tutorial review using-tutorials
+  - Using Tutorials
+  - "Step 1: List the available tutorials"
+  - "Step 4: Capture the workflow in a file"
+  - "Step 7: Pick every read-only tutorial command"
+  - tutorial review shows saved transcripts
+hint: Review `using-tutorials` from inside this shell.
+```
+
+Run `tutorial review using-tutorials`.
+
+Review reads the saved transcripts for the current run. Because this shell
+session is still in progress, the review output can show the earlier saved
+steps, but it cannot show this step until after you exit the shell and the
+step is recorded.
+
+At this point you have seen the main run-and-review workflow end to end:
+
+- `tutorial list` discovers what you can run
+- `tutorial run` starts or resumes one tutorial at a time
+- question steps can ask for input, one choice, or several choices
+- `tutorial review` inspects the saved record afterwards
+
+# Inspect one step of the saved run
+
+```tutorial-step
+required_patterns:
+  - tutorial review using-tutorials --step 1
+  - "Step 1: List the available tutorials"
+hint: Review only step 1 from inside this shell.
+```
+
+Run `tutorial review using-tutorials --step 1`.
+
+`--step N` narrows the review to one 1-indexed step instead of the whole
+run. Review normally shows the latest saved run for that tutorial; use
+`--run-id <id>` to pick an older one instead. `tutorial review --help`
+shows the full form.
+
+# Install a tutorial from a file or URL
+
+```tutorial-step
+kind: input
+answers:
+  - mode: regex
+    pattern: ^tutorial\s+install\s+\S+(?:\s+--force)?\s*$
+hint: Type an install command with a file path or URL.
+```
+
+Type a command such as `tutorial install ./lesson.md` or
+`tutorial install https://example.com/lesson.md --force`.
+
+`tutorial install <source>` copies a tutorial Markdown file into your
+installed tutorial directory so it appears in `tutorial list` alongside the
+built-ins. Add `--force` to overwrite an installed tutorial with the same
+`id`. This question step only records your answer, so you can practice the
+command safely without installing anything.

pytorial-0.1/src/tutorial/tutorials/writing-tutorials.md

@@ -0,0 +1,414 @@
+---
+id: writing-tutorials
+title: Writing Tutorials
+summary: Create a tutorial file, add shell, editor, and question steps, and load it.
+---
+
+# Create a tutorial directory
+
+```tutorial-step
+required_patterns:
+  - mkdir my-tutorials
+  - ls
+  - my-tutorials
+hint: Create `my-tutorials`, then list the workspace.
+```
+
+Create a directory named `my-tutorials`, then run `ls`.
+
+This lesson keeps the path `my-tutorials/greeting.md` invariant while you
+add one tutorial feature at a time.
+
+# Draft the smallest tutorial
+
+```tutorial-step
+edit_file: my-tutorials/greeting.md
+required_patterns:
+  - "id: greeting"
+  - "title: Greeting Tutorial"
+  - "summary: A tiny tutorial for saying hello."
+  - "# Say hello"
+  - echo hello
+```
+
+Open `my-tutorials/greeting.md` and write this tutorial:
+
+```md
+---
+id: greeting
+title: Greeting Tutorial
+summary: A tiny tutorial for saying hello.
+---
+
+# Say hello
+
+Run `echo hello`.
+```
+
+This is the smallest useful tutorial: front matter plus one top-level
+step.
+
+Because this step has no `kind`, no `edit_file`, and no metadata fence,
+the tutorial runner will open a shell for it.
+
+# Load the tutorial from disk
+
+```tutorial-step
+required_patterns:
+  - tutorial list --tutorial-path my-tutorials
+  - greeting
+hint: Point the standalone CLI at `my-tutorials`.
+```
+
+Run `tutorial list --tutorial-path my-tutorials`.
+
+If the file parses, `greeting` should appear in the list.
+
+# Add a contains match
+
+```tutorial-step
+edit_file: my-tutorials/greeting.md
+required_patterns:
+  - "```tutorial-step"
+  - "required_patterns:"
+  - "  - echo hello"
+```
+
+Keep the same tutorial and the same step, but add a metadata fence before
+the instructions:
+
+````md
+# Say hello
+
+```tutorial-step
+required_patterns:
+  - echo hello
+```
+
+Run `echo hello`.
+````
+
+Only one aspect changed: the step now has an explicit validation rule.
+It is still a shell step, because the metadata fence adds
+`required_patterns` but still does not add `kind` or `edit_file`.
+
+A bare string uses the default `contains` mode. That mode is the best
+default because the runner strips ANSI control noise and collapses
+whitespace before matching. Small differences such as trailing spaces
+from shell completion do not force authors to write regexes.
+
+# Contrast it with a regex match
+
+```tutorial-step
+edit_file: my-tutorials/greeting.md
+required_patterns:
+  - "required_patterns:"
+  - "  - mode: regex"
+  - '    pattern: (?m)echo hello(?:\s+)?$'
+```
+
+Keep the same tutorial, the same step title, and the same command, but
+replace the string rule with an explicit regex rule:
+
+````md
+# Say hello
+
+```tutorial-step
+required_patterns:
+  - mode: regex
+    pattern: (?m)echo hello(?:\s+)?$
+```
+
+Run `echo hello`.
+````
+
+Only one critical aspect changed: the matching mode. The command
+`echo hello` stays invariant, while the authored rule changes from a
+short normalized contains check to a regex that says more precisely what
+part of the transcript should match.
+
+Use regex when you need that extra control. Otherwise, keep the shorter
+string form.
+
+# Match shell output with a regex
+
+```tutorial-step
+edit_file: my-tutorials/greeting.md
+required_patterns:
+  - "required_patterns:"
+  - "  - mode: regex"
+  - "    pattern: (?m)^hello$"
+```
+
+Keep the same tutorial file, the same step title, and the same
+`echo hello` command, but change the regex so it matches the output line
+instead of the command line:
+
+````md
+# Say hello
+
+```tutorial-step
+required_patterns:
+  - mode: regex
+    pattern: (?m)^hello$
+```
+
+Run `echo hello`.
+````
+
+`(?m)` lets `^` and `$` mean line boundaries inside the recorded shell
+transcript. That is where regex starts to earn its keep: `contains` can
+only say that `hello` appears somewhere, while this rule matches one whole
+line of shell output.
+
+# Add an editor-backed step
+
+```tutorial-step
+edit_file: my-tutorials/greeting.md
+required_patterns:
+  - "# Edit a note"
+  - "edit_file: hello.txt"
+  - hello from the editor
+```
+
+Add this second step to the same file:
+
+````md
+# Edit a note
+
+```tutorial-step
+edit_file: hello.txt
+required_patterns:
+  - hello from the editor
+```
+
+Open `hello.txt` and add `hello from the editor`.
+````
+
+This now contrasts two different step backends in the same tutorial: a
+shell step with explicit matching metadata and an editor-backed step with
+`edit_file`. `edit_file` still selects the editor backend, while question
+steps use `kind`. `edit_file` and `kind` are mutually exclusive, so
+combining them is a parse-time error.
+
+# Add an input question
+
+```tutorial-step
+edit_file: my-tutorials/greeting.md
+required_patterns:
+  - "# Type the greeting"
+  - "kind: input"
+  - "answers:"
+  - "  - mode: regex"
+  - "    pattern: (?i)hello(?:\\s+)?$"
+```
+
+Add this third step to the same file:
+
+````md
+# Type the greeting
+
+```tutorial-step
+kind: input
+answers:
+  - mode: regex
+    pattern: (?i)hello(?:\s+)?$
+```
+
+Type `hello`.
+````
+
+Input questions reuse the same string-or-regex answer format as
+`required_patterns`. Only the interaction kind changes: the runner now
+prompts for one line of text instead of opening a shell or editor.
+
+# Add a single-select question
+
+```tutorial-step
+edit_file: my-tutorials/greeting.md
+required_patterns:
+  - "# Pick the shell command"
+  - "kind: single_select"
+  - "options:"
+  - "  - echo hello"
+  - "  - pwd"
+  - "  - ls"
+  - "answers:"
+  - "  - echo hello"
+```
+
+Add this fourth step to the same file:
+
+````md
+# Pick the shell command
+
+```tutorial-step
+kind: single_select
+options:
+  - echo hello
+  - pwd
+  - ls
+answers:
+  - echo hello
+```
+
+Choose the command that prints the greeting.
+````
+
+Single-select questions use literal option text. The learner may answer by
+number or by the full option, but the authored answer stays the option
+text itself.
+
+# Add a multi-select question
+
+```tutorial-step
+edit_file: my-tutorials/greeting.md
+required_patterns:
+  - "# Pick every inspection command"
+  - "kind: multi_select"
+  - "options:"
+  - "  - pwd"
+  - "  - ls"
+  - "  - echo hello"
+  - "answers:"
+  - "  - pwd"
+  - "  - ls"
+```
+
+Add this fifth step to the same file:
+
+````md
+# Pick every inspection command
+
+```tutorial-step
+kind: multi_select
+options:
+  - pwd
+  - ls
+  - echo hello
+answers:
+  - pwd
+  - ls
+```
+
+Choose every command that inspects the workspace.
+````
+
+Multi-select questions also use literal YAML lists. The learner may choose
+the correct options in any order, but authors still list the correct
+option texts explicitly under `answers`.
+
+# Add a shell check to the editor step
+
+```tutorial-step
+edit_file: my-tutorials/greeting.md
+required_patterns:
+  - "check_command:"
+  - 'test "$(cat hello.txt)" = "hello from the editor"'
+```
+
+Keep the same `# Edit a note` step, but add a filesystem-based shell check:
+
+````md
+# Edit a note
+
+```tutorial-step
+edit_file: hello.txt
+required_patterns:
+  - hello from the editor
+check_command: test "$(cat hello.txt)" = "hello from the editor"
+```
+
+Open `hello.txt` and add `hello from the editor`.
+````
+
+`check_command` is opt-in. The runner refuses to execute it unless the
+reader passes `--allow-shell-checks`. It runs in a separate
+`/bin/bash -lc` process with the tutorial workspace as its current
+directory, so it can inspect files there but it does not inherit shell
+variables or other session state from the interactive step. It is also
+AND-ed with `required_patterns`: both checks must pass before the step
+completes.
+
+# Test the tutorial you wrote
+
+```tutorial-step
+required_patterns:
+  - tutorial run --tutorial-path my-tutorials greeting
+  - "greeting $"
+  - "Step not complete yet: Say hello"
+hint: Start `greeting`, then leave its first shell with `exit`.
+```
+
+Run `tutorial run --tutorial-path my-tutorials greeting`.
+
+This still tests a different aspect from `tutorial list --tutorial-path
+my-tutorials`. Listing only proves that the file parses and the tutorial is
+discoverable. Running it proves that the authored tutorial still starts
+with the expected shell backend even after you add editor and question
+steps later in the file.
+
+Keep the tutorial file itself invariant here. Only the command changes: you
+now move from inspecting tutorial metadata to exercising the authored
+behaviour.
+
+For this step:
+
+1. Run `tutorial run --tutorial-path my-tutorials greeting`.
+2. When the nested shell opens with the `greeting $ ` prompt, type `exit`.
+3. The nested run should report `Step not complete yet: Say hello`.
+4. Exit this lesson's shell too so the transcript is recorded.
+
+# Iterate on one step with `tutorial develop`
+
+```tutorial-step
+required_patterns:
+  - tutorial develop --tutorial-path my-tutorials greeting 1
+  - "greeting $"
+  - "Verdict: FAIL"
+hint: Start develop for step 1, exit immediately, then keep the FAIL verdict and stop.
+```
+
+Run `tutorial develop --tutorial-path my-tutorials greeting 1`.
+
+For this step:
+
+1. Run `tutorial develop --tutorial-path my-tutorials greeting 1`.
+2. When the temporary `greeting $ ` shell opens, type `exit` immediately.
+3. Answer yes when `tutorial develop` asks whether the `FAIL` verdict is
+   correct.
+4. Answer no when it asks whether to run the step again.
+
+`tutorial develop` exercises one authored step in a temporary workspace,
+prints `PASS` or `FAIL`, and lets you edit and re-run that step without
+restarting the whole tutorial. We point at step `1` by number here, but the
+same command also accepts a regex that matches the step title. Develop also
+enables shell checks by default; pass `--deny-shell-checks` to turn them
+off for one session.
+
+# Inspect the finished tutorial
+
+```tutorial-step
+required_patterns:
+  - tutorial list --tutorial-path my-tutorials
+  - greeting
+  - cat my-tutorials/greeting.md
+  - "    pattern: (?m)^hello$"
+  - "kind: input"
+  - "kind: single_select"
+  - "kind: multi_select"
+  - "edit_file: hello.txt"
+  - 'check_command: test "$(cat hello.txt)" = "hello from the editor"'
+  - "    pattern: (?i)hello(?:\\s+)?$"
+hint: List the tutorials, then display the file you wrote.
+```
+
+Run `tutorial list --tutorial-path my-tutorials` and
+`cat my-tutorials/greeting.md`.
+
+At this point you have checked the same tutorial in three different ways:
+
+- `tutorial list --tutorial-path my-tutorials` shows that it loads
+- `tutorial run --tutorial-path my-tutorials greeting` shows that it runs
+- `cat my-tutorials/greeting.md` lets you inspect the final shell, editor,
+  shell-check, and question metadata directly