Feature: Scriptbook (runnable script documents)

Write this so someone with no background can follow.

Objective

Ship Scriptbook: documents authored in CentrMark (.cmk) that can be played on a developer machine (install steps, DNS checks, setup recipes). Run output lives in sidecars; the source document is never rewritten.

Upstream: dev-centr/scriptbook.

Illustrated model

Abstract playbooks

Essay

Intents, not shell translation

Three layers (not SLP, not shell translation)

Three layers: CentrMark the book, PlayTime the stage, Scriptbook the app
Figure 1. Cookbook, kitchen, waiter
Name Job

CentrMark (.cmk)

Markup only. No exec. No Equivalence Engine.

PlayTime

Engine in the Scriptbook library. Detect host, bind intents, run commands, write sidecars.

Scriptbook

App (scriptbook CLI today; DevCentr GUI later). Opens the book and drives PlayTime.
This is not Synchronous Literate Programming (that is `

tangle` / source sync).

This is not a bash-to-PowerShell rewriter. Author an intent (cli.install + tool id). PlayTime asks the Equivalence Engine for a command that fits this computer. Portable glue may stay as a Nushell cell.

A Linux apt script enters a hot-replace grinder and comes out as broken Windows commands
Figure 2. Do not put a bash script through a blender

Details: PlayTime · Host Awareness · GitHub spec/ until the hub deploy lands.

Not SLP

Synchronous Literate Programming (SLP) Scriptbook

Goal

Document ↔ source code sync (::: tangle, evolution scrubber)

Document ↔ shell/script execution

Output

Tangled source files

<file.cmk>.runs/ sidecars

Mutates .cmk?

Bi-directional edit may update AST/source

No — weave in UI only

See also Synchronous Literate Programming.

v0.1 surface

  • CLI: scriptbook run|status|clean-runs

  • Shells: auto / nu / sh / bash / pwsh

  • Library for future DevCentr GUI player

  • Example: GitHub Pages + Cloudflare HTTPS dance (with general-knowledge Nu checker)

Intent playbooks (v0.2)

  • ::: step [intent="cli.install" tool="gh"] — same file on Windows and Linux

  • Host Awareness snapshot first (PlayTime). Then Equivalence Engine bind. Never the reverse.

  • CLI: --format, --catalog, --answers (no TUI wizard yet)

  • ::: choose / when-answer / when-context for method branching

  • GUI player is still later — do not reimplement exec in the docs UI

DevCentr integration (later)

  • Open .cmk playbooks in-app; stream step progress; weave sidecar results beside narrative

  • Prefer PlayTime (Scriptbook library) over reimplementing exec in the docs UI

  • Questionnaire UX belongs in the app; ranking methods belongs in the Equivalence Engine