runbook-tutorials/workplans/archived/260929-RBT-WP-0004-local-runbook-ui.md

---
id: RBT-WP-0004
type: workplan
title: "Local runbook UI"
domain: infotech
repo: runbook-tutorials
status: finished
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: cancel
priority: medium
state_hub_task_id: "a33cbd52-8759-583f-a2f0-8ab926569346"
```

Cancelled 2026-09-29 (RBT-WP-0009): the run records are usable from the CLI for v0.1 packs (`rtut run ...`), and a terminal walk-through for v0.2 is not
needed to close this workplan. It is kept as RBT-WP-0006-T05. Original scope: `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: done
priority: medium
state_hub_task_id: "616255c2-091c-5948-8160-abd9dc69907f"
```

Done 2026-09-29 (RBT-WP-0009-T04): the run view is the evidence view; a closed run's record downloads as JSON and `rtut seal` verifies it.
The exercise-status diff no longer exists (retired, RBT-WP-0009-T01).

## 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: done
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: done
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: done
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: done
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: done
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: done
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.

## Delivered 2026-09-29: the v0.2 walk-through UI

`rtut/ui_v2.py` (tested over HTTP with 19 tests; rendering checked in headless Chromium screenshots of the flow, data and overview
views on a mid-run state). Three views of one run:

- **Guided flow** (main): framing shown first; a banner with the recommended next action and the other items possible in parallel;
  nested stages with goals, per-stage questions (datapoints saved with validation), numbered steps with owner and actor, idempotency,
  irreversible and manual-only marks; alternatives with the recommended one preselected; typed confirmation phrase for irreversible steps;
  override dialog (reason, acknowledged downstream risk, recorded as a deviation) for blocked steps and gates in manual mode; gates with per-check
  controls and waivers; retry that asks for the partial-application confirmation on non-idempotent steps; captures and pasted-output
  checks; feedback and closing as before.
- **Data**: every datapoint editable independently of the flow, grouped or filtered by dimension (click a tag), with provenance,
  plus artefacts (resolved locations) and actors.
- **Overview**: progress, per-stage state, gates, datapoint states, deviations, mode changes.
- **Modes**: manual, and auto-confirm with "check once", "run until it waits" and "take over"; a stop or push-through is shown.
  Projects can start v0.2 members in either mode.
- **Visual design**: a restrained stylesheet (hairlines, state pills that never rely on colour alone, highlighter accent for
  the recommended action, print rules). Dark theme is written but not verified in a browser.

## Feedback round after the first v0.2 hands-on (2026-09-29)

```task
id: RBT-WP-0004-T14
status: done
priority: high
state_hub_task_id: "28582e62-335c-57d5-9adc-6b9050268139"
```

Bernd's remarks, each handled and tested: (a) forms no longer ask for a name; the active user (`user-attributes`, app-level and reusable by
projects; `RTUT_USER`, saved settings or the OS login; `/user` page); (b) the showcase's irreversible step is now genuinely irreversible (the
logbook entry carries the exact time it was written); (c) a "Latest activities" section on the main page; (d) values that steps already used
can only be changed with an override and are recorded as `changed-after-use`, saves are all-or-nothing; (e) artefacts on the Data tab can be
opened and downloaded, with safety rules; (f) run start, finish and duration, per-step duration, and the average duration of successful
runs next to the score. Documented in `docs/run-spec.md` and `docs/maturity-and-projects.md`.

## App shell, theme, attribute-set management and project editing

```task
id: RBT-WP-0004-T15
status: done
priority: high
state_hub_task_id: "a6bf64b5-4432-5fc9-bdbe-5631b65e8343"
```

Done 2026-09-29 from Bernd's feedback (no way to switch theme, no navigation to user settings or attribute sets): a sidebar shell on every
page (Home, Projects, Runbooks, Attribute sets, Activity; you and a theme switch at the bottom; a top bar on narrow screens); a theme
switch that cycles system, light and dark and remembers the choice (`?theme=dark` also sets it); dedicated Projects, Runbooks and Activity
pages; attribute sets listed, inspected with their resolved values and sources, created and edited (values, requirement, note, extends;
secrets, bad names, unknown and circular `extends` refused, a refused save changes nothing); the project name, description and goal
editable from the project page. Bernd confirmed the theme and navigation. Not done: deleting an attribute set, editing templates.

## Closed runs locked; Home headlines as shortcuts

```task
id: RBT-WP-0004-T16
status: done
priority: high
state_hub_task_id: "2622084d-b5f7-5442-962f-2f7b1e87cd8d"
```

Done 2026-09-29 from Bernd's feedback: Home headlines link to their sidebar sections; the "Back to the runbook list" link is gone; closed runs are
locked (engine refuses changes, feedback included), sealed with a hash and made read-only, tampering is shown and disqualifies the run as maturity
evidence; the closing form takes optional feedback so abandoned runs are not silent; a closed run shows its feedback read-only (no "Change my
feedback"), or no feedback section at all. See `docs/run-spec.md`.

## Project runs in the UI

```task
id: RBT-WP-0004-T17
status: done
priority: high
state_hub_task_id: "1394fb8f-a24e-5516-a7c3-e31ca1a3a40e"
```

Done 2026-09-29: the project page has "Run the whole project" (mode choice, history of project runs); a project run page shows progress, the
next or open member, the member table with status, progress and links, an override for out-of-order starts, auto-confirm controls (check once,
run until it waits, take over or hand over), a log, and the closing form. Member run pages link back to their project run; the activity
feed includes project run events. Tested over HTTP; visual check pending.

## 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.