---
id: RBT-WP-0004
type: workplan
title: "Local runbook UI"
domain: infotech
repo: runbook-tutorials
status: active
flavor: implementation
owner: claude
topic_slug: stack
created: "2026-09-29"
updated: "2026-09-29"
depends_on: [RBT-WP-0003]
state_hub_workstream_id: "bbd03473-fcf7-5b20-a295-e9ff45fb7ecc"
---

## Goal

The interface that made the operator ask for this: a local web UI (and a
terminal fallback) that shows where you are in a runbook, what to do next, and
what you have proven.

## Review the existing console's interaction model

```task
id: RBT-WP-0004-T01
status: done
priority: high
state_hub_task_id: "8309d778-3688-5cb3-bb34-18f87b66dbf3"
```

Done 2026-09-29 with Bernd. Findings and consequences are in `docs/ux-review-2026-09-29.md`; the model they imply is proposed in `docs/pack-spec-v0.2.md`.

## Build the step view

```task
id: RBT-WP-0004-T02
status: done
priority: high
state_hub_task_id: "e15c22b6-60eb-5a54-9d22-b268897fcf4d"
```

Parameter form, ordered steps with owner tags, rendered copyable commands,
"done when" with confirm/verify, rollback shown beside each step, progress
overview, resume after restart. Localhost only, no external calls, whynot-design
posture, works without JavaScript frameworks.

## Terminal mode

```task
id: RBT-WP-0004-T03
status: todo
priority: medium
state_hub_task_id: "a33cbd52-8759-583f-a2f0-8ab926569346"
```

`rtut run <pack>` walking the same run record in the terminal, for hosts
without a browser.

## Evidence view and export

```task
id: RBT-WP-0004-T04
status: todo
priority: medium
state_hub_task_id: "616255c2-091c-5948-8160-abd9dc69907f"
```

Show the run record, export it as non-secret JSON, and produce the exercise-status
diff from RBT-WP-0003-T04.

## Fix the check, record and lock-in cycle

```task
id: RBT-WP-0004-T05
status: done
priority: high
state_hub_task_id: "d635f972-0377-5581-a8fe-c01ef89559cd"
```

Done 2026-09-29 against the lighthouse showcase (tested over HTTP; a browser pass by Bernd is still the real check). Defects found in review: a ticked manual check shows "passed" while the step stays
`running`, and unticking changes nothing; blocked steps show no Start button and no
reason. Make the cycle explicit (check, record, mark done), and show what a blocked
step is waiting for. Follow-up done 2026-09-29 from Bernd's first hands-on: the command and
Copy button appear only once a step is started (done steps keep the command as a record);
"Mark done" and "Mark failed" sit left of the comment field; a first "Mark failed" without a
comment only warns, a second click fails without one; every action returns to the current
step instead of the top of the page.

## Questionnaire flow on the v0.2 model

```task
id: RBT-WP-0004-T06
status: todo
priority: high
state_hub_task_id: "261bf74f-f5cd-55bb-9a96-12767418c980"
```

Unblocked: RBT-WP-0007 (engine) is finished. The serial guided flow is the main interface: stages with
progress, the recommended next action, other ready actions, framing shown at the
start of each stage, and gates shown at stage exit.

## Dimension view

```task
id: RBT-WP-0004-T07
status: todo
priority: high
state_hub_task_id: "16db09c7-7707-5d17-aab3-5d8eab2c1fce"
```

Unblocked: RBT-WP-0007 (engine) is finished. A random-access table of datapoints (with `nil/set/err/ok`
state) grouped or filtered by dimension (actor, role, privilege, subsystem, kind),
editable independently of the flow, plus the artefacts view.

## Overview

```task
id: RBT-WP-0004-T08
status: todo
priority: high
state_hub_task_id: "23d3f5cc-e844-5077-9a4a-0435c189d98b"
```

Unblocked: RBT-WP-0007 (engine) is finished. State transparency at a glance: stage progress, gate states
and waivers, datapoint completeness by dimension.

## Visual design

```task
id: RBT-WP-0004-T09
status: wait
priority: medium
state_hub_task_id: "53c74197-4747-5bdd-9b7c-8bdc42b7c1f5"
```

Theme and layout at the quality of the old console or better: spacing, hierarchy,
dark mode, visual guidance. Implemented in the renderer only; no presentation fields
in the pack spec.

## Typed-phrase confirmation

```task
id: RBT-WP-0004-T10
status: wait
priority: medium
state_hub_task_id: "ddbca5e1-dcf6-5c2a-b3e2-497d2a82ba23"
```

Confirm button for reversible steps, typed phrase for irreversible ones, per the v0.2
`reversible` field.

## Mode switch and override dialog

```task
id: RBT-WP-0004-T11
status: todo
priority: high
state_hub_task_id: "99320417-8261-556b-8932-4947cfd8ce11"
```

Unblocked: RBT-WP-0007 T06-T07 are finished. Choose manual or auto-confirm per run (with timeout and
push-through controls). In manual mode, an override dialog lists unmet preconditions and
the downstream risk before continuing; deviations show in the overview.

## Feedback collector

```task
id: RBT-WP-0004-T12
status: done
priority: medium
state_hub_task_id: "483e7472-ff22-5611-8010-9cf96ac34ec9"
```

Done 2026-09-29: after "All steps done." the run view offers three smileys and a comment
(what felt strange or unclear, ideas to optimize). Stored in the run record (history kept,
latest wins, secrets refused); `rtut feedback <pack.yaml>` lists the latest per run.
Follow-up: fold feedback into the overview and use it to prioritize pack refinements.

## Run outcome, score, exercise recording and captures

```task
id: RBT-WP-0004-T13
status: done
priority: high
state_hub_task_id: "d35e129c-cfcc-538f-a4bf-76761d13a28a"
```

Done 2026-09-29 from Bernd's review: runs are finalized as succeeded, failed or abandoned
(stale open runs count as abandoned after 7 days); a runbook's score (tried, succeeded, failed,
abandoned, open, feedback tally) is shown in the list and on the pack page, with a list of its
runs; finalizing a succeeded run offers an explicit "Record pack as exercised" that shows the
change before writing it to `pack.yaml`; steps can capture the command run and its output, and
`output-contains` checks can be verified against pasted output. Documented in `docs/run-spec.md`.
Open: run histories are per machine (`.local/`), so a shared or committed history is still
to be decided.

## Acceptance Criteria

- Bernd can complete the SSH tutorial pack in the UI without pasting outputs to an agent.
- The old console's seven runbooks can be walked in the new UI at equal or better clarity.
- The UI refuses to display or store anything matching the secret markers.