net-kingdom/workplans/NK-WP-0044-runbook-packs-for-runbook-tutorials.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	related	state_hub_workstream_id
NK-WP-0044	workplan	Provide NetKingdom runbook packs for the runbook-tutorials engine	infotech	net-kingdom	finished	implementation	claude	netkingdom	2026-09-29	2026-10-03	NK-WP-0009	82414324-e9cf-5581-af9e-b0122411d7bf

The guided console invented here (NET-WP-0016) now has a home: the runbook-tutorials repository (workplans RBT-WP-0002 to RBT-WP-0006). This workplan is net-kingdom's side: keep the existing console working, and offer NetKingdom runbooks as packs in runbooks/, following runbook-pack/v0.1.

Wrap the existing console as a legacy pack

id: NK-WP-0044-T01
status: done
priority: high
state_hub_task_id: "44a2d9a7-c0bc-5099-89fb-f6a3fa0c2e50"

runbooks/security-bootstrap-console/pack.yaml, engine legacy-command. Verified end to end: rtut launch starts make security-bootstrap-ui, port 8876 answers, and the process stops on exit. The console itself is unchanged.

Convert the SSH certificate tutorial to a native pack

id: NK-WP-0044-T02
status: done
priority: high
state_hub_task_id: "ea4b5cb2-cb7d-5349-9057-bf2657690c79"

runbooks/ssh-certificates/pack.yaml (parameters actor, pubkey, tunnel; owner-tagged steps; verify and rollback). It validates; it is unexercised.

Convert the OpenBao and flex-auth tutorials

id: NK-WP-0044-T03
status: done
priority: high
state_hub_task_id: "ba1a41a7-b40d-5312-851e-93c613ac9b27"

Ported to v0.2 on 2026-09-29 (RBT-WP-0009-T06): all three NetKingdom packs now use stages, actors, datapoints with dimensions, gates, idempotency and framing; the OpenBao pack models "validate a real ceremony record" as alternatives recommended by a datapoint (there is no skip in v0.2); the live flex-auth steps are auto_confirm: manual-only so auto-confirm never mints tokens on its own. All 13 cluster-free checks were re-run through the engine and pass. docs/tutorials/openbao-operating-path.md and protected-system-flex-auth.md become native packs. The flex-auth pack's live part uses the informed-decision pin and the negative tests N1-N3 as parameterized steps. N4 (expired token) is not in the pack: it needs a ten-minute wait and a held token, so it stays a documented manual check in the markdown tutorial. The markdown stays until the packs are exercised. Verified without a run record: the ten offline and read-only verify commands were executed and passed; the cluster-touching steps (port-forward and token calls) have not been run.

Validate packs in this repository

id: NK-WP-0044-T04
status: done
priority: medium
state_hub_task_id: "1423d9d7-ce11-5fd3-9905-3566f947b0a9"

make runbooks-validate runs the rtut validator from the runbook-tutorials checkout (RTUT_HOME, default ~/runbook-tutorials).

Exercise the packs through the UI

id: NK-WP-0044-T05
status: done
priority: high
state_hub_task_id: "2d99180e-25ff-51db-8208-b0320c8ec7e3"

The UI, project runs and maturity are ready (RBT-WP-0004 and RBT-WP-0008 are finished). Bernd runs the SSH, OpenBao and flex-auth packs in the UI, ideally inside a rehearsal project so the clean runs count as maturity evidence; the engine records outcomes, and NK-WP-0009 T03-T05 close on those receipts. Start with rtut check . and open the packs from the runbook list.

Dry-runs 2026-10-01 (Claude, through rtut.run2; no environment, manual checks self-attested, so no maturity): nk.object-storage-sts and nk.openbao-operating-path ran clean. nk.ssh-certificates stopped at sign: its defaults (actor agt-claude-railiance01, key ~/.ssh/id_ed25519.pub) do not exist on this workstation (ops-warden inventory holds agt-state-hub-bridge, agt-codex-interhub-*, adm-example, atm-backup-daily; no id_ed25519 key). Nothing was issued. Decision needed from Bernd on which actor and key the rehearsal uses; then fix the pack defaults. Engine gap (rtut CLI cannot run v0.2 packs) sent to runbook-tutorials (6e366f35-43a7-4e55-8622-40626a4acbec). Project trial-2 is the lighthouse showcase and holds no NetKingdom pack, so it is not T05 evidence.

Rehearsal actor 2026-10-02: Bernd approved an inert test actor, not a master key. Added agt-rehearsal (agt, 2h, principal rehearsal-inert-nohost, no host trusts it) to the workstation warden inventory, key ~/.ssh/agt-rehearsal_ed25519; the nk.ssh-certificates defaults now point at it and its tunnel step is an honest alternative (no target yet = not proven). warden sign is still denied by flex-auth (unknown_actor_resource): actors live in ops-warden's production registry. Request sent to ops-warden for the sanctioned registration; net-kingdom does not edit their registry. A systematic pre-production testing environment (test CA, test principals, test hosts) is Bernd's later topic.

ops-warden answered 2026-10-02 (21c85dc3-754e-41fc-a271-02255054e12d): no production registry change. A rehearsal config (WARDEN_CONFIG=~/.config/warden/rehearsal/warden.yaml, throwaway local CA, no flex-auth gate, no prod trust) signs for the inert agt-rehearsal. The pack now has a warden_config datapoint defaulting to it. nk.ssh-certificates dry-ran clean (cert: test CA, principal rehearsal-inert-nohost only, 2h). This proves the signing mechanics, not the policy gate; the tunnel stage stays "not proven" until a test target exists. Dry-runs of packs 1-3 are all clean; Bernd's UI rehearsal is the remaining T05 work. A systematic pre-production environment (ops-warden's option b) is Bernd's later topic.

First operator run, 2026-10-02 (Bernd, project nk-rehearsal): nk.ssh-certificates step sign failed, recorded with a note: the WARDEN_CONFIG= prefix was not applied, so warden used the production config. Retried with the prefix and it passed. Cause: the requirement lived only as an inline prefix in the command. Pack fix to apply after the run completes (a changed revision resets the evidence): state the rehearsal-config requirement as its own step with a check that proves which config is selected. QA proposals (structured env:, must_exist datapoints, rtut smoke, failure hints, failures as pack defects) sent to runbook-tutorials (37848b4c-1b30-410f-bcc3-3a79a4d59ab1).

Rehearsal status 2026-10-02: nk.object-storage-sts, nk.ssh-certificates and nk.openbao-operating-path are rehearsed (one clean rehearsal run each, records sealed, exported by Bernd). nk.protected-system-flex-auth has not been run. T05 stays open for it. Pack fixes are batched until that run is in: explicit rehearsal-config step and config check (ssh), route step BrokenPipe noise, plus whatever pack 4 surfaces. Feedback so far: ssh "more understandable"; openbao "Soso, we need to make it easier to use, but it helps" (neutral; needs specifics).

Retire the markdown verifier

id: NK-WP-0044-T06
status: done
priority: low
state_hub_task_id: "1b747058-d4df-5f5c-bd63-e85d46dd094e"

Once the tutorials are packs, tools/tutorial-verify and make tutorials-verify are replaced by runbooks-validate, and docs/tutorials/ becomes a pointer.

Port the seven console runbooks

id: NK-WP-0044-T07
status: done
priority: low
state_hub_task_id: "8628d5eb-6e5d-501d-a8f5-960d6b5db8f4"

The security bootstrap console's seven runbooks (privacyIDEA realm repair, key material compromised, generate new unseal keys, emergency lock-down, restore drill, token revocation, user lifecycle dry-run) can become native v0.2 packs. They are linear procedures with 23 command blocks and need none of the gaps G1 to G7 in runbook-tutorials/docs/console-mapping.md. The console itself stays a permanent legacy pack.

Ported on 2026-09-29: runbooks/privacyidea-realm-repair, openbao-key-compromise, openbao-rotate-unseal-keys, openbao-emergency-lockdown, openbao-restore-drill, openbao-token-revocation and user-lifecycle-dry-run. All validate (make runbooks-validate, 11 packs). They are unexercised: no command was run. Secret-handling steps are auto_confirm: manual-only, irreversible steps use the pack confirm_phrase, and token and share entry stays at hidden prompts.

Acceptance Criteria

• The console still works and is launched by the engine without changes to it.
• Every NetKingdom pack validates; maturity is derived from run history, not declared.

Rehearsal complete and verifier retired — 2026-10-03

Bernd ran nk.protected-system-flex-auth (run 20261002-235239-c46227): 15 steps and both gates passed, no deviations; the engine derives rehearsed. All four packs are applied in nk-rehearsal (T05). T06: tools/tutorial-verify, its tests, make tutorials-verify* and docs/tutorials/TEMPLATE.md are removed; docs/tutorials/README.md is a pointer; the three markdown tutorials stay as superseded reference (the flex-auth one still holds check N4, which the pack omits). Recorded feedback: ssh "more understandable", openbao neutral ("we need to make it easier to use, but it helps"), flex-auth neutral ("ok, but this is hard tasks"). The four HTTP codes of the live checks were not captured as evidence in the run. Pack improvements (explicit rehearsal-config step and check in the ssh pack, route BrokenPipe noise, easier-to-use feedback) are deliberately deferred to the next pack revision so the rehearsed evidence is not reset now.