Documentation › Using the Builder

Using the Builder

The Builder is a single HTML file. Open it in a browser from your own disk, drop a plain-text runbook on it, and save the interactive runbook it makes. It installs nothing and makes no network requests: your runbook is never sent anywhere.

Getting the Builder

1. Download it from runbookbuilder.com. You register with your name and email, enter the code we send, and get thinware-runbook-builder-1.2.5.zip.
2. Check the zip against the SHA-256 shown on the download screen, before you open it:

   (Get-FileHash .\thinware-runbook-builder-1.2.5.zip -Algorithm SHA256).Hash
   sha256sum thinware-runbook-builder-1.2.5.zip

   If it differs, download again and do not use the file.
3. Extract the zip. It holds runbook-builder.html, the Builder; runbook-design-guide.md, the Design Guide to give the people and the AI tools that draft runbooks for you; sample-runbook.txt, a runbook that only reads from a Windows computer, to try first; and README.txt, which carries the SHA-256 of runbook-builder.html itself, for checking a copy of the Builder you were given or have kept.
4. Open runbook-builder.html in a browser: Chrome or Edge 102 or later, or Firefox 112 or later (Safari 16.4 should work but is not tested). Keep it anywhere you like; it works from a local folder, a file share or a USB stick. The About button at the top right shows the version and the license notice.

3.1 Building an interactive runbook

1. Write the plain-text runbook in a file ending in .txt, following Formatting for the Builder.
2. Open runbook-builder.html in a browser and drop the plain-text runbook onto the drop zone, or press Choose file…. Only the drop zone takes a file; one dropped anywhere else on the page is ignored.
3. If the Builder lists problems, correct the plain-text runbook, save it, and drop it again. Line numbers are the plain-text runbook's line numbers. Troubleshooting explains each message.
4. Check the preview (Section 3.2), then press Save interactive runbook. The Builder suggests the plain-text runbook's name ending in .html.
5. Publish the interactive runbook with its hash (Section 3.3).

To change a runbook later, edit the plain-text runbook and build again. Never edit an interactive runbook. Keep the plain-text runbook: it is the source, and the interactive runbook is built from it.

The Builder works opened from disk and makes no network requests. Your runbook is never sent anywhere.

3.2 Checking the preview

The Builder shows the interactive runbook as it will be saved. Before saving, confirm:

1. The step list on the left shows every step, in order, with the right numbers.
2. No step's code block contains the next step's title.
3. The number of steps matches what you expect. The Builder's summary shows the count.
4. The Settings card shows a field for every setting, and typing in a field changes the Settings code and any later line that loads that setting.
5. The title, Prepared by:, Version: and Compatible with: lines appear under the title as you wrote them.

Checked steps and values typed into the preview are not kept, and Save progress and Load progress are shown but switched off there.

3.3 Publishing with a hash

After saving, the Builder shows the SHA-256 hash of the saved file, with a Copy button.

1. Give the interactive runbook to the people who will follow it.
2. Send the hash by a different route from the file: the ticket, the change record, or a separate email. A hash sent in the same email as the file proves nothing.
3. Before using it, the operator checks that the file gives the same hash. Letter case does not matter.

PowerShell:

(Get-FileHash .\archive-app-logs.html -Algorithm SHA256).Hash

Bash:

sha256sum archive-app-logs.html

Anything that rewrites the file on the way changes the hash, such as converting line endings or saving the file from an editor. A different hash means: get a fresh copy from the author, and do not use the file.

3.4 Upgrading to a new version of the Builder

If you asked for release emails when you registered, we write when a new version is out; Release notes says what changed. Download it the same way; the old copy can simply be deleted.

An interactive runbook keeps the version of the Builder it was built with, and keeps working as it is. To move it to a new version, build it again with the new Builder:

1. Drop the plain-text runbook onto the new Builder. If you no longer have it, drop the interactive runbook (.html) instead: the Builder takes the runbook text out of it. Files from every earlier version are accepted, including those made with the earlier Runbook Viewer.
2. If you dropped an interactive runbook, press Save plain-text runbook and keep the .txt file it saves. It is the runbook text exactly as it was, and it is the source for every later change.
3. If the Builder lists problems, the runbook breaks a rule that is checked in this version. Correct the lines listed in the plain-text runbook, and drop the .txt file.
4. Save the interactive runbook and publish it with its new hash (Section 3.3). The hash always changes, because the file now holds the new version of the Builder.

Progress saved from the old interactive runbook still loads into the new one, as long as the runbook text is unchanged.