# INTENT

## Why this repository exists

Operators should be able to carry out real IT administration and operation tasks
by following a guided interface instead of a document. Raw runbooks fail in the
same ways every time: the operator loses their place, pastes the wrong value,
skips a verification, or records nothing. This repository provides the
runbook-tutorial engine and user interface that presents a runbook as a
sequence of parameterized steps with visible state, gates, copyable commands,
verification and rollback, and non-secret evidence of what actually happened.

## Direction

- **One engine, many packs.** The engine is generic. The runbooks themselves
  are *runbook packs* that live in a `runbooks/` directory of the repository
  that owns the procedure. A pack stays next to the system it operates, so its
  owner can change both together. This repository owns no operational content
  beyond examples and its own conformance packs.
- **Existing runbooks keep working.** The NetKingdom security bootstrap console
  predates this repository. Its guided flow is carried across through a legacy
  adapter first and migrated into the pack format only where that pays off.
- **Parameters, not copies.** A runbook declares its parameters; the engine
  renders commands with the operator's values and never asks for secrets.
- **Evidence over assertion.** A step is done when its declared check has
  passed and its outcome is recorded. How far a runbook can be trusted (its
  maturity) is earned from clean runs in named environments, not declared.
- **Never a secret vault.** The engine does not collect, store, log or
  transmit secret values. It shows the command; the operator runs it.
- **Guide, not executor by default.** Steps are run by the operator. Any
  automated execution is opt-in per step, explicit, and audited.

## Relationship to other repositories

- `net-kingdom` provides the first runbook pack (security bootstrap) and the
  operator tutorials, and the console this engine grows out of.
- Each repo that wants guided operation adds `runbooks/<pack>/` and follows the
  pack specification published here.
- `state-hub` records workplans; this repo does not become a task tracker.