# runbook-tutorials

A user interface specialized to present runbook tutorials that with parameters
can guide through actual IT administration and operation tasks.

- **Intent:** `INTENT.md` · **Scope:** `SCOPE.md`
- **Pack specification:** `docs/pack-spec.md` (v0.1, runnable) and `docs/pack-spec-v0.2.md` (v0.2: stages, gates, datapoints, actors, modes; validates, not yet runnable). Schemas in `rtut/schema/`. UX findings: `docs/ux-review-2026-09-29.md`
- **Packs live where the procedure lives:** `runbooks/<pack>/pack.yaml` in the owning repo.
  Examples: `net-kingdom/runbooks/`, and here `runbooks/example-hello/` and
  `runbooks/showcase-lighthouse/` (a harmless story to try the UI on).

## Install

Python 3.12 or newer.

```bash
make install        # editable install with the test dependencies (pip install -e ".[test]")
make check          # validate every pack, attribute set, project and template
make test           # run the tests
```

A plain `pip install .` works too and provides the `rtut` command; the JSON schemas ship inside the package.

```bash
python3 -m rtut validate <repo-root>      # validate every pack
python3 -m rtut list <repo-root>          # id, engine, maturity, title
python3 -m rtut show <pack.yaml>          # steps with owners and done-when
python3 -m rtut render <pack.yaml> <step> -p name=value
python3 -m rtut launch <pack.yaml>        # legacy-command packs: start the existing console
python3 -m rtut maturity <pack.yaml>      # draft | reviewed | rehearsed | proven | stale, from run history
python3 -m rtut review <pack.yaml> --by you     # record a review of the current revision
python3 -m rtut project list|validate|status|attrs|new|run <repo-root> ...   # projects, attribute sets, templates
python3 -m rtut ui <repo-root> [<repo-root> ...]   # local web UI on 127.0.0.1:8877: projects, templates, runbooks; v0.1 and v0.2 runs (guided flow, data view, overview)
python3 -m rtut run new|start|verify|done|finalize <pack.yaml> ...   # the same run record from the terminal
make test
```

Status: see `SCOPE.md`; the workplans are in `workplans/`.