runsheets 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b4caf43ab35c8816f90d794e6dba06e3fd3644cd838c89c9987bbe0f60ab786
+  data.tar.gz: 39cd9610b55e341bc1b664443a509a2269f7397c190e28f38fcbcc6c9287f2db
+SHA512:
+  metadata.gz: cec8d91aa87096dfae4548d1eb39df3c9b6d57e0d2176d24e12550f9ff7a21c0487e0f850b7fd0c5fd9178f7cd471057e40771c3a2918b897ec7f57fa63b1282
+  data.tar.gz: 2d960f098334bf2b7900eae5084c1fa722a27b6c115d6da26e4020e4cd9b5c32a546d265ba448a36d4bbb6dfcfdb730ae16d7ab0b3112ae6308d341f54c16ba0

data/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.0.1] - 2026-10-11
+
+First release. runsheets turns a markdown runbook into a local web page
+where marked commands get a Run button, and records everything that
+happens during a run as a *runsheet*.
+
+### Runbooks
+
+- A runbook is a directory (`runbook.md` with YAML front matter, ordered
+  `steps/`, optional `verify.md` and `rollback.md`) or a single markdown
+  file whose `##` headings are the steps.
+- Front matter declares `inputs` (with secrets) and `interpreters` that map
+  other languages, such as `sql` through `psql`, to a command.
+- `runsheets --init PATH` scaffolds a starter runbook; `runsheets --check`
+  reports authoring warnings.
+- Runbooks are re-read when their files change on disk.
+
+### The fenced block convention
+
+- The info string marks a block as `run`, `destructive`, `background`,
+  `terminal` or `expect`.
+- `run` blocks execute `bash`, `sh`, `zsh`, `ruby` or any mapped language
+  as a fresh process group with a per-step timeout.
+- `destructive` blocks need a typed confirmation, checked on the server.
+- `background` blocks get Start and Stop buttons and appear in a Running
+  panel on every page.
+- `terminal` blocks are run by the operator, who confirms with "I ran this"
+  and an optional note.
+- `text expect` blocks are compared with the output of the block above
+  them. `{{any}}` matches text that changes on each run, and a mismatch
+  shows the output and the expected text side by side with the differences
+  highlighted.
+
+### Libraries, search and documents
+
+- `runsheets DIR` on a folder of runbooks opens a library: a folder tree
+  with a filter box, each folder's `README.md`, and a summary of each
+  runbook with its inputs, steps and previous runs.
+- Full-text search across every runbook in the library, with ranked
+  results and highlighted snippets.
+- Relative links to other markdown files open as pages: another runbook,
+  or a plain document with nothing executable.
+- A Checks page gathers every verify document and runs them all with one
+  button.
+
+### Sessions and the run record
+
+- Everything between starting and stopping runsheets is one session, with
+  an engineer and a reason (from the start page, or `--engineer` and
+  `--why`).
+- The session page holds timestamped notes, every run's progress, the tail
+  of the session log, and an End session button. Ending a session, or
+  Ctrl-C, closes each run as `completed`, `partial` or `opened`. A session
+  left open by a killed process is closed as `interrupted` at the next
+  start.
+- Each run records the exact command, output, exit status, timing, step
+  acknowledgements and notes in `run.json` and a readable `run.md`.
+- `session.log` records every action and line of output, timestamped and
+  levelled, and echoes it to the terminal.
+- Run history, and a diff for every block whose code has changed since a
+  past run.
+
+### Security
+
+- Binds to loopback by default. Every request needs the session key the
+  printed `?token=` link gives the browser as a cookie, so other accounts
+  on the machine see nothing; every state-changing request also needs the
+  per-process session token and an allowed Host header.
+- Secret inputs are redacted from output and logs, however the output is
+  split, and never written back into the page.
+- Every page has a Content-Security-Policy with a per-response nonce, so a
+  `<script>` in a runbook's markdown does not run, and the page's script
+  acts only on blocks runsheets rendered, so a copied Run button does
+  nothing. Run refuses a block edited since the page loaded. Files served
+  from a runbook are sandboxed and cannot follow a symlink out of it.
+- Anything a block leaves running in its process group is stopped when
+  the block finishes.
+- A project `./config/runsheets.yml` cannot by itself bind runsheets to a
+  non-loopback address.
+
+### Settings
+
+- Layered settings through `myway_config`. Command-line flags override
+  `RUNSHEETS_*` environment variables, which override `./config/runsheets.yml`,
+  which overrides `~/.config/runsheets/runsheets.yml`, which overrides the
+  bundled defaults.
+- `runsheets --dump` prints the settings in force as a config file.
+
+### Examples
+
+- `examples/` holds directory and single-file runbooks: `hello`,
+  `staging-teardown`, `db-maintenance.md`, `disk-space-triage.md` with the
+  plain documents it links to, and `asgard-tasks.md`, whose blocks call
+  asgard tasks.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+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.

data/README.md

@@ -0,0 +1,277 @@
+# runsheets
+
+> **Note:** This is a proof-of-concept and a work in progress. Features,
+> file formats, and the CLI may change without notice.
+>
+> Runbooks are common among DevOps engineers but a little foreign to me.
+> Please [open an issue](https://github.com/MadBomber/runsheets/issues) and
+> let me know where I get this concept wrong. I appreciate all feedback and
+> contributions.
+>
+> See the [CHANGELOG.md](https://github.com/MadBomber/runsheets/blob/main/CHANGELOG.md)
+> file for the latest changes.
+
+**Full documentation:** <https://madbomber.github.io/runsheets>. This
+README is the overview; the documentation site covers authoring, the
+block convention, the web UI, the run record, settings and the security
+model in detail.
+
+Executable runbooks. A runbook (a directory of markdown files, or a single
+markdown file) becomes a local web page
+where the steps read like a doc site, the commands the author marked as
+runnable get a Run button, and everything that happens during a run is
+recorded: the exact command, its output, exit status, timing, and the
+operator's acknowledgements of the manual steps.
+
+The rendering is the vehicle. The run record, the *runsheet*, is the point.
+
+Every block kind in the convention below is live, a runbook can be a
+directory or a single markdown file, and everything between starting
+runsheets and stopping it is one *session* with its own log. Vocabulary: the document is
+the *runbook*; the record of one runbook's run is the *runsheet*.
+
+## Install
+
+```bash
+gem install runsheets
+```
+
+Requires Ruby 3.4 or newer.
+
+## Run
+
+```bash
+runsheets                         # serve the bundled examples/directory_based_runbooks/hello on http://127.0.0.1:4567/
+runsheets path/to/runbook         # serve a runbook directory (runbook.md + steps/)
+runsheets path/to/runbook.md      # serve a single all-in-one markdown file
+runsheets path/to/runbooks        # a directory of runbooks: choose one in the browser
+runsheets --open path/to/runbook  # and open the browser
+runsheets --check path/to/runbook # load it, print authoring warnings, exit
+runsheets --init path/to/new      # scaffold a runbook (a .md path makes a single file)
+```
+
+The argument is one of three things: a runbook directory, a single
+all-in-one markdown file whose `##` headings are the steps (see
+[Single-file runbooks](docs/runbooks/structure.md#single-file-runbooks)),
+or a directory holding several of either, in folders nested as deep as
+you like. A markdown file is a runbook only when it starts with YAML front
+matter that has a `title`; any other markdown file is a plain document that
+a runbook can link to (see
+[Runbooks and Documents](docs/concepts/runbooks.md)). Started on such a library, the browser opens on a folder tree in
+the left pane; selecting a runbook shows its description, prerequisites,
+inputs, steps and previous runs in the main pane, with the inputs form and
+a **Start run** button.
+A `README.md` in a folder is shown as that folder's description. The
+search box in the header searches the full text of every runbook. Try the
+examples bundled with the gem:
+
+```bash
+cd "$(dirname "$(gem which runsheets)")/.."                            # the installed gem's directory
+runsheets --open examples                                              # all five, pick one in the browser
+runsheets --open examples/directory_based_runbooks/hello               # safe to run: every block kind
+runsheets --check examples/directory_based_runbooks/staging-teardown   # a realistic AWS teardown
+runsheets --open examples/single_md_file_runbooks/db-maintenance.md    # a single all-in-one file, sql blocks via psql
+runsheets --open examples/single_md_file_runbooks/disk-space-triage.md # links to plain documents, kept out of the tree
+```
+
+Options: `--port`, `--bind` (default loopback), `--runs-dir` (where run
+records go; default `~/.local/share/runsheets/runs`), `--open`, `--check`,
+`--init`, `--config FILE`, `--dump` to print the settings in force as a
+config file (redirect it to save them), and for the session `--engineer`,
+`--why`, `--log-level`, `--verbose` and `--quiet`. Settings are layered: the command line beats
+`RUNSHEETS_*` environment variables (`RUNSHEETS_PORT`, `RUNSHEETS_DIR` for
+the runbook, ...), which beat `./config/runsheets.yml` (or the file `--config` or
+`RUNSHEETS_CONFIG` names), which beats `~/.config/runsheets/runsheets.yml`,
+which beats the defaults bundled in `lib/runsheets/config/defaults.yml`. See
+[docs/running/cli.md](docs/running/cli.md#settings).
+
+## Sessions
+
+Everything between starting `runsheets` and stopping it is one *session*.
+It starts by asking who you are and why you are starting it (or take them
+from `--engineer` and `--why`); the why is the session's first note. Then:
+
+- **Select a runbook** and fill in its inputs: that starts its *run*. Run
+  buttons are disabled until then.
+- **Work through the steps**, or open any step, in any order, and run just
+  that. A run is the record executions are written to, not an order you
+  have to follow (see [docs/concepts/runs.md](docs/concepts/runs.md#a-run-is-a-record-not-a-sequence)).
+- **Switch runbooks** whenever you like. Every run stays open, and
+  selecting a runbook again returns to its run.
+- **Write notes** on the session page as things happen.
+- **End the session** with the button on the session page, or Ctrl-C.
+  Every run closes with the status its work earns: `completed`,
+  `partial`, or `opened`.
+
+Everything you do, and every line of output, goes to a `session.log`
+written as it happens and echoed to the terminal, like a Rails log:
+
+```text
+2026-10-10 01:17:19.589 INFO  [disk-space-triage 010-check-free-space #acd50b22502a] execute bash via bash
+2026-10-10 01:17:19.589 INFO  [#acd50b22502a] $ df -h "$TARGET_DIR"
+2026-10-10 01:17:19.602 INFO  [#acd50b22502a] > /dev/disk3s5   1.8Ti   1.4Ti   391Gi    79%   /System/Volumes/Data
+2026-10-10 01:17:19.651 INFO  [#acd50b22502a] finished exit 0 in 0.06s
+```
+
+`--log-level`, `--verbose` and `--quiet` tune it; see
+[docs/running/run-record.md](docs/running/run-record.md).
+
+## A runbook is a directory
+
+```text
+staging-teardown/
+  runbook.md              front matter + preamble (required)
+  steps/
+    010-confirm-nothing-to-preserve.md
+    020-stop-the-pipeline.md
+    030-drain-ecs-services.md
+  verify.md               whole-procedure checks (optional)
+  rollback.md             what to do when it fails partway (optional)
+  assets/                 images referenced by the markdown
+```
+
+The directory name is the runbook's slug. Steps are ordered by filename;
+numeric prefixes with gaps leave room to insert.
+
+### runbook.md
+
+```yaml
+---
+title: Staging Infrastructure Teardown and Rebuild
+when_to_use: >
+  The deployed stacks cannot be updated in place.
+prerequisites:
+  - AWSAdministratorAccess in the staging account
+  - The staging branch is ready to fast-forward
+blast_radius: >
+  Destroys the staging database, container images, and DNS.
+escalation: Stop and contact the platform owner if any stack delete fails twice.
+tags: [aws, staging, destructive]
+inputs:
+  - name: AWS_PROFILE
+    prompt: AWS profile with admin access
+    default: staging-admin
+  - name: DB_PASSWORD
+    prompt: Database password
+    secret: true
+interpreters:
+  ruby: bin/rails runner -
+---
+Everything below the front matter is the preamble and renders on the
+landing page.
+```
+
+`inputs` become a form when a run starts. Values are exported as
+environment variables to every executed block, so blocks refer to them as
+`$NAME` and stay copy-pasteable into a terminal. A blank field falls back
+to the value given for the same name earlier in the session (never for a
+secret), then the process environment, then `default`. A `secret` input is masked in
+the form and never written to the run record.
+
+`interpreters` maps a language to the command that runs a file of it. The
+defaults are `bash`, `sh`, `zsh` and `ruby`; a Rails project would map
+`ruby` to `bin/rails runner -`, and `sql: psql -X -v ON_ERROR_STOP=1 -f`
+makes `sql run` blocks execute through `psql`.
+
+### Single-file runbooks
+
+One markdown file works too: the front matter is the runbook's, every
+`##` heading is a step, attributes go in an HTML comment after the
+heading (`<!-- kind: verify, timeout: 30 -->`), and sections headed
+**Verify** and **Rollback** stand in for the extra files. See
+`examples/single_md_file_runbooks/db-maintenance.md`.
+
+### Step files
+
+```yaml
+---
+title: Drain the ECS services
+kind: automated          # automated | manual | verify
+destructive: false
+timeout: 600             # seconds, for executable blocks in this step
+cwd: .                   # working directory, relative to the runbook
+---
+```
+
+The body is ordinary markdown: the instruction, the command, and the "how to
+tell it worked" line that every good step carries. `kind` defaults to
+`automated` when the body has an executable block, otherwise `manual`.
+
+## The fenced block convention
+
+The info string's first word is the language. Any following words are
+flags. A block with no flag is display only, whatever its language.
+
+| Info string | Behaviour |
+| --- | --- |
+| ```` ```bash ```` | Display only. |
+| ```` ```bash run ```` | Run button. Executed with the run's inputs in the environment; stdout, stderr and exit status recorded. |
+| ```` ```bash destructive ```` | Run button behind a typed confirmation code issued by the server. Implies `run`. |
+| ```` ```ruby run ```` | Same, executed with `ruby` (or the runbook's `interpreters.ruby`). |
+| ```` ```bash background ```` | Start and Stop buttons. No timeout; output streams into the page; listed in the sidebar's Running panel; stopped when the run ends. |
+| ```` ```bash terminal ```` | No Run button. "Run this in your own terminal, then confirm." An **I ran this** button records the confirmation, with an optional note. |
+| ```` ```text expect ```` | Not executed. Compared with the output of the executable block above it; a mismatch is shown side by side with the differences marked. `{{any}}` matches anything within a line. |
+
+An unknown flag, or `run` on a language that cannot execute, renders with a
+visible warning instead of being ignored. `runsheets --check` lists them.
+
+Each execution is a fresh process with the runbook directory as its working
+directory. Nothing carries over between blocks except the environment.
+
+## The run record
+
+```text
+~/.local/share/runsheets/runs/
+  sessions/<session-id>/
+    session.json    who, when, the notes, the runs, how it ended
+    session.log     every action and its output, appended as it happens
+  <runbook-slug>/<session-id>/
+    run.json        steps, blocks, timestamps, exit codes, acknowledgements
+    run.md          the same as a readable transcript
+    blocks/
+      020-stop-the-pipeline-1.1.cmd   the exact code that ran
+      020-stop-the-pipeline-1.1.out   its stdout + stderr
+```
+
+Records live outside the runbook so captured output never lands next to
+the docs in a repository. A runbook's landing page lists its previous
+runs; each points back to its session. A session left running by a killed
+process is closed as `interrupted` the next time runsheets starts.
+
+## Security posture
+
+- Binds to loopback by default. There is no multi-user story. `--bind` to
+  another address is possible, warns, and is a bad idea off a network you
+  control.
+- Executes only blocks whose info string opts in. Everything else is inert.
+- Every request needs this start's session key, which the browser gets by
+  opening the link runsheets prints. Another account on the same machine
+  can reach the port but sees nothing.
+- Every state-changing request needs a per-process token that only a page
+  served by this process knows, and the `Host` header must be a loopback
+  name. Together these stop a page on another origin from driving the tool.
+- Every page sets a Content-Security-Policy that lets only the page's own
+  script run, and the script acts only on blocks runsheets itself rendered.
+  Raw HTML in a runbook renders, but neither its script nor a copied Run
+  button does anything, so a runbook cannot drive the tool either.
+- Anything a block leaves running (`cmd &`) is stopped when the block
+  finishes; a long-running process belongs in a `background` block.
+- Destructive blocks show the blast radius and need a confirmation code the
+  server issues per block, checked server-side.
+- Secret inputs reach the child process but never the run record. Captured
+  output is redacted before it is written; plain string replacement, so an
+  encoded secret is not caught.
+- The tool writes nothing inside the runbook directory.
+- Stopping the server ends the session: every run is closed and whatever it
+  left running is stopped. Secret values never reach the session log.
+
+## Design
+
+The model (`Runbook`, `Library`, `Step`, `Block`, `Renderer`, `Executor`,
+`Expectation`, `Search`, `RunRecord`, `Run`, `Session`, `SessionLog`) has
+no dependency on Sinatra and is tested in isolation; `Web` and `Pages` are
+tested with rack-test.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/bin/runsheets

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Make the script runnable straight from a checkout (bin/ on PATH, no
+# `bundle exec`): put the sibling lib/ first on the load path. For an
+# installed gem this resolves to the gem's own lib/, which is already there.
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "runsheets"
+
+exit Runsheets::CLI.run(ARGV)

data/examples/about-the-examples.md

@@ -0,0 +1,40 @@
+# About these examples
+
+This file has no front matter, so it is a plain document, not a runbook.
+It is not listed in the library tree; runbooks link to it.
+
+Start runsheets on this directory to choose among the examples:
+
+```bash
+runsheets --open examples
+```
+
+The examples are grouped by shape, and each group is a folder in the
+library tree:
+
+- `directory_based_runbooks/`: runbook directories, a `runbook.md` beside
+  a `steps/` folder holding one file per step.
+- `single_md_file_runbooks/`: single-file runbooks, every step in one
+  markdown file, together with the plain documents they link to.
+  `runbooks_with_scripts/` inside it holds a runbook whose blocks call
+  asgard tasks from the `.loki` files beside it.
+
+| Example | Shape | Safe to run |
+| --- | --- | --- |
+| [Hello, runsheets](directory_based_runbooks/hello/runbook.md) | runbook directory | yes |
+| [Disk space triage](single_md_file_runbooks/disk-space-triage.md) | single file | yes, it only reads |
+| [Monthly PostgreSQL maintenance](single_md_file_runbooks/db-maintenance.md) | single file | needs a database |
+| [Staging infrastructure teardown](directory_based_runbooks/staging-teardown/runbook.md) | runbook directory | no, read it |
+| [Runbook tasks from local .loki files](single_md_file_runbooks/runbooks_with_scripts/asgard-tasks.md) | single file with `.loki` task files | yes, it only reads; needs asgard |
+
+## Plain documents
+
+Besides this file, two plain documents back the disk space triage runbook:
+[the disk usage glossary](single_md_file_runbooks/disk-usage-glossary.md) beside it, and
+[the cleanup policy](single_md_file_runbooks/policies/cleanup-policy.md) in a folder of its own.
+
+A runbook can link to a plain document anywhere under the directory
+runsheets was started on (here, `examples/`), with an ordinary relative
+link. Started on a single runbook instead (`runsheets examples/directory_based_runbooks/hello`),
+that runbook's own directory is the limit, so a link climbing out of it,
+like the one `directory_based_runbooks/hello/runbook.md` makes to this file, does not resolve.

data/examples/directory_based_runbooks/hello/rollback.md

@@ -0,0 +1,11 @@
+---
+title: Rollback
+---
+
+Nothing in this runbook needs rolling back. In a real runbook this file holds
+the steps that undo a partial run, and it sits one click away in the sidebar
+of every step so nobody has to scroll for it when something goes wrong.
+
+```bash
+echo "nothing to undo"
+```

data/examples/directory_based_runbooks/hello/runbook.md

@@ -0,0 +1,40 @@
+---
+title: Hello, runsheets
+when_to_use: >
+  You want to see what an executable runbook looks like, or you need a
+  fixture that exercises every block kind without touching anything real.
+prerequisites:
+  - A shell with bash and ruby on the PATH
+  - Nothing else; every command here is harmless
+escalation: There is nobody to call. Read the step again.
+tags: [example, safe]
+inputs:
+  - name: NAME
+    prompt: Who should be greeted?
+    default: world
+  - name: SECRET_WORD
+    prompt: A word that must never appear in the run record
+    default: hunter2
+    secret: true
+---
+
+# Hello, runsheets
+
+This runbook exists to show the shape of a runbook directory and the fenced
+block convention. Nothing in it changes your machine.
+
+A runbook is a directory:
+
+```text
+hello/
+  runbook.md       this file: front matter and preamble
+  steps/*.md       one file per step, ordered by filename
+  verify.md        whole-procedure checks
+  rollback.md      what to do when it goes wrong
+```
+
+Start a run from the panel above, then walk the steps in the sidebar.
+
+This runbook sits in a directory of examples. [About these
+examples](../../about-the-examples.md) is a plain document two levels up,
+linked like any other markdown file.

data/examples/directory_based_runbooks/hello/steps/010-say-hello.md

@@ -0,0 +1,33 @@
+---
+title: Say hello
+kind: automated
+timeout: 30
+---
+
+The inputs you gave when starting the run are exported as environment
+variables, so a block can refer to them as `$NAME` and still be pasted into a
+terminal unchanged.
+
+```bash run
+echo "Hello, $NAME!"
+echo "Running block $RUNSHEETS_BLOCK of step $RUNSHEETS_STEP in run $RUNSHEETS_RUN_ID"
+```
+
+A `text expect` block after it shows what the output should look like.
+Once the block has run, the page compares the two and hides the expect
+block: a match just says so, and a mismatch shows both side by side with
+the differences marked. The run id is different every time, so the
+expected text has `{{any}}` in its place, which matches anything on that
+line. It is a hint, not a verdict.
+
+```text expect
+Hello, world!
+Running block 010-say-hello-1 of step 010-say-hello in run {{any}}
+```
+
+A block with no flag is just displayed. This one is the same command, but it
+has no Run button:
+
+```bash
+echo "Hello, $NAME!"
+```

data/examples/directory_based_runbooks/hello/steps/020-inspect-ruby.md

@@ -0,0 +1,28 @@
+---
+title: Inspect the Ruby that will run things
+kind: automated
+---
+
+Ruby blocks execute with `ruby` unless the runbook's front matter maps the
+language to another command, such as `bin/rails runner -`.
+
+```ruby run
+puts "Ruby #{RUBY_VERSION} on #{RUBY_PLATFORM}"
+puts "cwd: #{Dir.pwd}"
+puts "greeting for: #{ENV.fetch('NAME', '(unset)')}"
+```
+
+Other languages stay display only until there is a safe way to route them.
+This SQL is for a client you open yourself:
+
+```sql
+SELECT count(*) FROM runs WHERE status = 'completed';
+```
+
+Some things cannot be run from a page at all, because they are interactive.
+Do them in your own terminal, then click **I ran this** so the run record
+shows you did, with a note if you want one:
+
+```bash terminal
+read -r -p "Press Enter when you have looked at the output above: "
+```

data/examples/directory_based_runbooks/hello/steps/030-take-a-breath.md

@@ -0,0 +1,11 @@
+---
+title: Take a breath
+kind: manual
+---
+
+Not every step is a command. A manual step is an instruction; the operator
+reads it, does it, and marks the step done, optionally with a note that goes
+into the run record.
+
+1. Look at the sidebar. Steps that have run show a mark next to them.
+2. Decide whether you want to see a failure next, or skip it.

data/examples/directory_based_runbooks/hello/steps/035-keep-a-clock-running.md

@@ -0,0 +1,21 @@
+---
+title: Keep a clock running
+kind: automated
+---
+
+Some things have to stay up while you work through later steps: a tunnel, a
+log tail, a port forward. A `background` block has Start and Stop buttons
+instead of Run. Its output streams into the page while it runs, it has no
+timeout, and it is listed in the sidebar's **Running** panel on every page
+with a Stop button of its own.
+
+```bash background
+while true; do
+  date "+%H:%M:%S  still here"
+  sleep 1
+done
+```
+
+Leave it running and move to the next step, or stop it here. Anything still
+running when the run is finished is stopped for you, and the execution is
+recorded as `stopped` rather than as a failure.

data/examples/directory_based_runbooks/hello/steps/040-exercise-failure.md

@@ -0,0 +1,26 @@
+---
+title: Exercise a failure
+kind: automated
+destructive: true
+timeout: 5
+---
+
+This step is marked destructive in its front matter even though it does no
+harm, so you can see the confirmation flow. Both blocks are safe.
+
+The first one exits non-zero on purpose. The page shows the exit status and
+the run record keeps it:
+
+```bash destructive
+echo "about to fail on purpose" >&2
+exit 3
+```
+
+The second one sleeps longer than the step's five second timeout, so the
+process group is killed and the execution is recorded as timed out:
+
+```bash run
+echo "sleeping"
+sleep 30
+echo "never printed"
+```

data/examples/directory_based_runbooks/hello/steps/045-check-the-greeting.md

@@ -0,0 +1,18 @@
+---
+title: Check the greeting
+kind: verify
+---
+
+A `verify` step is a read-only check. It runs in its place during the
+procedure, and it also appears on the **Checks** page with every other
+check, where **Run all** runs them one after another inside the run.
+
+```bash run
+echo "Hello, $NAME!" | grep -q "Hello, $NAME!" && echo "greeting looks right"
+ruby -e 'puts "ruby answers: #{6 * 7}"'
+```
+
+```text expect
+greeting looks right
+ruby answers: 42
+```

data/examples/directory_based_runbooks/hello/verify.md

@@ -0,0 +1,18 @@
+---
+title: Verify
+kind: verify
+---
+
+Whole-procedure checks. These should pass after every run.
+
+```bash run
+test -n "$NAME" && echo "NAME is set to $NAME"
+test -d "$RUNSHEETS_RUN_DIR/blocks" && echo "run directory exists: $RUNSHEETS_RUN_DIR"
+```
+
+A secret input never reaches the run record, even when a block prints it.
+The value is replaced before the output is written:
+
+```bash run
+echo "the secret is $SECRET_WORD"
+```