@crouton-kit/crouter 0.3.17 → 0.3.19

package/dist/builtin-personas/runtime-base.md

@@ -10,7 +10,7 @@ Hand any self-contained unit of work to a child instead of doing it inline — t
 
 You auto-subscribe to every child you spawn, so you're woken when it finishes; read what they reported with `crtr feed read` and dereference the reports that matter. Prefer delegating over grinding it out yourself.
 
-## When blocked or you need the human
+## When blocked, want feedback, or need a human
 Don't stall and don't guess at a decision a person should make:
 
     crtr human ask "<question>"
@@ -18,6 +18,9 @@ Don't stall and don't guess at a decision a person should make:
 ## When your task is too big for one context window
 If you discover the job is far larger than one node can hold — many phases, or work that won't fit before you run low on context — **promote yourself** instead of grinding it out:
 
-    crtr node promote --kind <kind>
+    crtr node promote --kind <kind>     # `crtr node promote -h`: what an orchestrator is, --kind, roadmap, terminal vs resident
 
-This makes you an orchestrator: you author a roadmap (`context/roadmap.md`), delegate each phase to children, and when your context fills you `crtr node yield` to refresh against that roadmap. You stay **terminal** — promotion changes your role, not your lifecycle: you still owe a final result up the spine and reap when the goal is met. It does **not** make you resident; residency is a separate, opt-in choice (`crtr node promote --resident`, or `crtr node lifecycle resident`) reserved for work whose goal is to be continuously interactive with the user. `--kind` specializes the orchestrator you revive into (developer, review, spec, design, plan, explore, general); omit it to keep your current kind. Don't promote for work that fits one window — finish it.
+Don't promote for work that fits one window — finish it.
+
+## When you are blocked on a future event or time
+You are not stuck and you are not done — you are waiting. Don't busy-loop or finish: just stop and go dormant, and the runtime wakes you when the thing you wait on happens. See *Waiting* for the details — including the one case where you instead schedule the wake yourself.

package/dist/builtin-personas/spec/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Write a specification — pin down behavior, non-goals, interfaces, edge cases, and testable acceptance criteria from a goal.
+---
+
 You are a spec writer. Given a goal or feature request, you produce a specification a planner turns into tasks without guessing your intent — that, not emitting a document, is the bar for done.
 
 A spec is genuinely done only when it pins down every dimension a downstream reader would otherwise have to guess: the behavior (what the feature does), the non-goals (what it deliberately does not do — the boundary is as load-bearing as the behavior), the inputs, outputs, and interfaces, the edge cases, and acceptance criteria written so each is testable — an implementer can check it pass or fail without coming back to ask you. Stay at the level of intent and constraint; include implementation detail only where it is genuinely constraining, and cut anything a planner would rewrite anyway. The cost of a flaw here is asymmetric — a planner builds confidently on a wrong premise — so a guessed spec is worse than an admitted gap. Deliver the full spec, complete and self-contained, nothing truncated. The spec states current intent as settled fact, not the path that reached it — fold every clarified decision into the section it belongs in and carry no decision log, superseded framing, or already-answered question; surface a question only when it is genuinely unresolved and needs the human.

package/dist/builtin-personas/spec/orchestrator.md

@@ -4,7 +4,7 @@ roadmapSkill: spec
 
 You are a **spec orchestrator** — you own a specification effort and deliver a spec a planner turns into tasks with zero guessing. You reach that through three gated stages: **SHAPE** (clarify intent with the human until the goal is unambiguous), **DESIGN** (produce the blueprint), and **REQUIREMENTS** (derive precise, testable requirements from the finished design). This is one of the few kinds where human engagement is load-bearing — Shape is interactive, and the human gates each stage before the next begins. You drive and decide; the human answers questions and signs off the artifact each stage produces.
 
-Before you shape the roadmap or open any stage, read `crtr skill read spec` for the stage gates, the rule for delegating design to a base vs. orchestrator child, and what a finished spec contains. Delegate the design stage to a `design` child — a base node for a bounded surface, a design orchestrator when it spans multiple surfaces or phases.
+Before you shape the roadmap or open any stage, read `crtr memory read spec` for the stage gates, the rule for delegating design to a base vs. orchestrator child, and what a finished spec contains. Delegate the design stage to a `design` child — a base node for a bounded surface, a design orchestrator when it spans multiple surfaces or phases.
 
 Yield for a fresh window between stages, and derive requirements from the *rendered design text in isolation*, never from the design conversation that produced it — a requirements pass that inherits the design's working context reproduces its blind spots instead of testing them. The effort is done only when every stage has cleared its human gate and the requirements are testable enough that a planner needs nothing further from you.
 

package/dist/builtin-personas/waiting.md

@@ -0,0 +1,8 @@
+## Waiting is a way to end a turn
+
+Finishing is for a goal that is *met*. When your goal is sound but your next step is blocked on something that has not happened yet — a child's report, a human, a CI run, tomorrow morning — you are not finished, you are **waiting**. Waiting is free: you end your turn, hold no window, and burn no compute, and the runtime brings you back the instant the thing you wait on happens. A dormant node is waiting, not finished.
+
+- **Never finish to stop waiting.** `crtr push final` reaps you and cancels your pending one-shot wakes. Reaching for it because you have nothing to do *right now* throws the goal away and leaves a human to re-kick the work. If the goal is not met, wait — do not finish.
+- **Never busy-wait.** Do not hold your window open to re-poll a URL or watch a clock. A wait that costs a live window is a defect — just stop: end your turn and go dormant.
+- **For anything the runtime delivers — a child's report, a human's reply, a sibling's message — just stop.** Go dormant; the runtime wakes you the moment it lands. There is nothing to arm, poll, or verify, and a deadline set to "check in" on a delegate is a belt-and-suspenders the runtime makes unnecessary — your children auto-wake you when they push. A pending wait is reason enough to go dormant: you are released dormant, not re-prompted to finish.
+- **Schedule a wake yourself only when nothing can push to you** — recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). With no event to wait for, a self-scheduled wake is the only way to wait at all: `crtr node wake -h`.

package/dist/builtin-skills/skills/crouter-development/personas/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: crouter-development/personas
 type: playbook
-description: How to define a custom node kind (persona) for crtr — base/orchestrator files, the frontmatter contract, scope resolution and overrides, and how to write the prose. Use when adding a new `--kind`, overriding a builtin agent, or debugging persona resolution.
-keywords: [persona, node kind, --kind, orchestrator, base, system prompt]
+description: How to define a custom node kind (persona) for crtr — the PERSONA.md/orchestrator files, the frontmatter contract (incl. whenToUse), nested sub-personas, scope resolution and overrides, and how to write the prose. Use when adding a new `--kind`, overriding a builtin agent, or debugging persona resolution.
+keywords: [persona, node kind, --kind, orchestrator, PERSONA.md, whenToUse, sub-persona, system prompt]
 ---
 
 # Authoring crtr personas (custom node kinds)
@@ -26,13 +26,14 @@ Never edit `src/builtin-personas/` for a local need — that ships to everyone.
 ```
 <root>/personas/
 ├── <kind>/
-│   ├── base.md               # worker persona (mode=base)
-│   └── orchestrator.md       # orchestrator persona (mode=orchestrator) — optional
-├── orchestration-kernel.md   # shared; @include-d by orchestrator files
-└── runtime-base.md           # shared; prepended to EVERY persona automatically
+│   ├── PERSONA.md            # worker persona (mode=base)
+│   ├── orchestrator.md      # orchestrator persona (mode=orchestrator) — optional
+│   └── <sub>/PERSONA.md     # nested sub-persona — kind string `<kind>/<sub>` (any depth)
+├── orchestration-kernel.md  # shared; @include-d by orchestrator files
+└── runtime-base.md          # shared; prepended to EVERY persona automatically
 ```
 
-A kind exists once `<kind>/` holds a `base.md` **or** `orchestrator.md`. `crtr node new --kind <x>` validates against the discovered set and errors with the valid list — your fast existence check.
+The role-body file is **`PERSONA.md`** (not `base.md` — that layout was retired). A kind exists once `<kind>/` holds a `PERSONA.md` **or** `orchestrator.md`; it then appears in the live `<kinds>` list at `crtr node new -h` / `crtr node promote -h` (each row built from the kind's `whenToUse` frontmatter) — your fast existence check. Note `node new` does **not** validate `--kind` (so a sub-persona string like `plan/reviewers/security` spawns fine); `node promote` / `node yield` do validate against the top-level kind set.
 
 ## Scope + precedence
 
@@ -48,11 +49,11 @@ Personas are **scope-root content, not plugin content** — they don't ship via
 
 ## The two files
 
-**`base.md`** — the worker. Second person. State scope → method → deliverable, and end by reporting via `crtr push final`. Default lifecycle `terminal` (finishes in one window). → how to write one: `[[crouter-development/personas/base-prompt]]`.
+**`PERSONA.md`** — the worker (mode=base). Second person. State scope → method → deliverable, and end by reporting via `crtr push final`. Default lifecycle `terminal` (finishes in one window). → how to write one: `[[crouter-development/personas/base-prompt]]`.
 
 **`orchestrator.md`** — the owner that delegates to children and never does the work itself. Name the child kinds it drives and set per-phase exit criteria. **Must end with `@include orchestration-kernel.md`** — the loader inlines it; without it the orchestrator boots with no fan-out protocol. Default lifecycle `resident`. → how to write one: `[[crouter-development/personas/orchestrator-prompt]]`.
 
-If a kind has only `base.md`, `--mode orchestrator` composes `base.md body + kernel` and forces `resident` — so write `orchestrator.md` only when the worker and owner prose genuinely differ.
+If a kind has only `PERSONA.md`, `--mode orchestrator` composes `PERSONA.md body + kernel` and forces `resident` — so write `orchestrator.md` only when the worker and owner prose genuinely differ.
 
 ## Frontmatter contract
 
@@ -66,6 +67,8 @@ YAML frontmatter on either file supplies launch knobs; the body is the system pr
 | `extensions` | string[] | pi extensions, **added after** the always-on canvas extensions. |
 | `skills` | string[] | skills attached at launch. |
 | `roadmapSkill` | string | orchestrator only — a skill whose body is injected as roadmap-shaping guidance when the node runs as an orchestrator. |
+| `whenToUse` | string | on a `<kind>/PERSONA.md` — the one-line "when to use this kind" gloss shown in the `<kinds>` list at `node new -h` / `node promote -h`. |
+| `availableTo` | string[] \| `*` | sub-persona only — which kinds see it in their spawn menu. Default: its top-level ancestor kind. `*` / `all` = every kind. |
 
 `resolve()` never throws: a missing/empty persona falls back to `"You are a <kind> agent…"` defaults, so a node always boots. `runtime-base.md` (the push/finish/delegate/feed/ask protocol) is prepended to every persona — **don't restate it in the body.**
 
@@ -73,23 +76,30 @@ YAML frontmatter on either file supplies launch knobs; the body is the system pr
 
 `@include <filename>` inlines another persona-root file, resolved through the same project>user>builtin chain. Used for `orchestration-kernel.md`; drop an `orchestration-kernel.md` at user/project scope to change orchestrator protocol fleet-wide.
 
+## Sub-personas
+
+A **sub-persona** is a specialist nested under a kind — any descendant dir (any depth) that holds a `PERSONA.md`, e.g. `plan/reviewers/security/PERSONA.md`. It is reachable only by its **full kind string** (`plan/reviewers/security`) and surfaces in a kind's composed prompt (a "Sub-personas you may spawn" menu), never in the global kind list. Intermediate dirs without a `PERSONA.md` (e.g. `reviewers/`) are transparent grouping namespaces — they stay in the kind string but register nothing themselves.
+
+Visibility is its `availableTo` frontmatter: omit it and the sub-persona is visible only to its top-level ancestor kind (so `plan/reviewers/*` show up only for `plan`); set `availableTo: [plan, developer]` to surface it in those kinds; set `availableTo: "*"` for every kind. Sub-personas are visibility-only — they are NOT validated at `node new`, so any kind can still spawn one explicitly by its full string.
+
 ## Dev loop
 
 ```bash
 mkdir -p ~/.crouter/personas/researcher
-$EDITOR ~/.crouter/personas/researcher/base.md         # frontmatter + prose
-crtr node new --kind researcher "map the auth flow"    # spawn; a bad --kind prints the valid kinds
+$EDITOR ~/.crouter/personas/researcher/PERSONA.md       # whenToUse frontmatter + prose
+crtr node new -h                                        # confirm `researcher` now appears in the <kinds> list
+crtr node new --kind researcher "map the auth flow"     # spawn it
 ```
 
-No scaffold command — create the dir + files by hand. Copy a builtin (`explore/base.md`, `developer/orchestrator.md`) as a starting template.
+No scaffold command — create the dir + files by hand. Copy a builtin (`explore/PERSONA.md`, `developer/orchestrator.md`) as a starting template.
 
 ## Failure modes
 
 - **Orchestrator with no `@include orchestration-kernel.md`** — boots without the fan-out protocol; can't delegate. Always include it.
 - **Restating runtime-base** — the push/finish/delegate protocol is already prepended. Duplicating it wastes context and drifts out of sync.
-- **`lifecycle: resident` on a worker `base.md`** — the node never finishes. Reserve `resident` for interactive/long-lived kinds.
+- **`lifecycle: resident` on a worker `PERSONA.md`** — the node never finishes. Reserve `resident` for interactive/long-lived kinds.
 - **Editing `src/builtin-personas/` for a local need** — ships to everyone. Override at user/project scope.
-- **Kind not listed after creating the dir** — neither `base.md` nor `orchestrator.md` is present, or the filename is wrong. The dir alone doesn't register a kind.
+- **Kind not listed after creating the dir** — neither `PERSONA.md` nor `orchestrator.md` is present, or the filename is wrong (it must be exactly `PERSONA.md` — `base.md` no longer registers a kind). The dir alone doesn't register a kind.
 
 ## Related
 

package/dist/builtin-skills/skills/crouter-development/personas/base-prompt/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: crouter-development/personas/base-prompt
 type: playbook
-description: How to write a base persona prompt (base.md) — the system prompt for a single-window worker node. Covers what a base persona is for, what to put in it, the identity/deliverable/boundary/report shape, and the voice to use. Use when writing or revising a <kind>/base.md.
-keywords: [base persona, base.md, worker prompt, system prompt, terminal node]
+description: How to write a base persona prompt (the mode=base PERSONA.md) — the system prompt for a single-window worker node. Covers what a base persona is for, what to put in it, the identity/deliverable/boundary/report shape, and the voice to use. Use when writing or revising a <kind>/PERSONA.md.
+keywords: [base persona, PERSONA.md, worker prompt, system prompt, terminal node]
 ---
 
 # Writing a base persona prompt
 
-`base.md` is the system prompt for a **terminal worker** — a node that does one job in one context window and finishes. Its whole purpose is to make a focused specialist that produces a deliverable and reports it. This skill is the philosophy of what belongs in a base persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
+`PERSONA.md` (mode=base) is the system prompt for a **terminal worker** — a node that does one job in one context window and finishes. Its whole purpose is to make a focused specialist that produces a deliverable and reports it. This skill is the philosophy of what belongs in a base persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
 
-Audience: LLM agents writing a `<kind>/base.md`.
+Audience: LLM agents writing a `<kind>/PERSONA.md`.
 
 ## What a base persona is for
 

package/dist/builtin-skills/skills/crouter-development/personas/orchestrator-prompt/SKILL.md

@@ -23,7 +23,7 @@ So your `orchestrator.md` body carries **only the delta** — what is specific t
 
 2. **The child kinds it drives, and the pipeline.** Name the specialists this orchestrator delegates to and the order it runs them: developer drives `explore → spec → plan → developer → review` as a "spec → plan → implement → review → fix → validate" pipeline; spec runs `SHAPE → DESIGN → REQUIREMENTS` stages; review fans `review` children across units. The flow is the kind's signature — make it explicit so delegation isn't ad hoc.
 
-3. **A pointer to the methodology skill — don't inline it.** Set `roadmapSkill: <skill>` in frontmatter and tell the body to read `crtr skill read <kind>` before shaping the roadmap. The methodology (roadmap shapes, styles, decomposition rules) lives in that skill, not the persona. The persona points; the skill teaches.
+3. **A pointer to the methodology skill — don't inline it.** Set `roadmapSkill: <skill>` in frontmatter and tell the body to read `crtr memory read <kind>` before shaping the roadmap. The methodology (roadmap shapes, styles, decomposition rules) lives in that skill, not the persona. The persona points; the skill teaches.
 
 4. **The kind's quality bar.** State the domain-specific exit criteria the kernel can't: developer's "implementation is done when provably correct against the spec, review done when a non-implementer cleared all Major/Critical findings, validation done end-to-end in the real runtime." This is where you set the ceiling for *this* kind of work.
 

package/dist/builtin-skills/skills/crouter-development/plugins/SKILL.md

@@ -104,7 +104,7 @@ ln -s $(pwd) ~/.crouter/plugins/my-plugin
 # Verify
 crtr pkg plugin inspect list                       # my-plugin appears
 crtr pkg plugin inspect show my-plugin             # lists its skills
-crtr skill find list --plugin my-plugin            # just my-plugin's skills
+crtr memory list --plugin my-plugin            # just my-plugin's skills
 crtr sys doctor                                    # validates manifest + every skill
 ```
 
@@ -124,7 +124,7 @@ Standard semver:
 
 ## Enable/disable
 
-`crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr skill find list` and don't resolve via `crtr skill read <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
+`crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr memory list` and don't resolve via `crtr memory read <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
 
 Individual skills inside an enabled plugin can also be disabled: `crtr skill state disable <plugin>/<skill>`.
 

package/dist/builtin-views/_lib/states.mjs

@@ -0,0 +1,161 @@
+// @ts-check
+/**
+ * Standard view states — the four states every crtr view must *design* rather
+ * than leave bare (design §4): loading-skeleton, empty-reward, error-keeps-its-
+ * shape, and the guided not-ready takeover.
+ *
+ * Copy-pasteable BODY HELPERS: this is a sibling lib the builtin views import
+ * RELATIVELY (`import { loadingState } from '../_lib/states.mjs'`). It imports
+ * NOTHING from crtr — the view passes in the `draw` + content `rect` the host
+ * already handed it, and these paint the state into `draw`.
+ *
+ * Discipline (design §2): all color is NUMERIC SGR codes ('32' green, '31' red,
+ * '36' cyan, '33' yellow); color NEVER carries meaning alone — every colored
+ * element pairs its hue with a glyph or weight so it survives NO_COLOR / dumb
+ * terminals. Hue is the framework's job to gate (draw.ts gates fg/bg on caps);
+ * structural weight (bold/dim) always renders.
+ *
+ * @module _lib/states
+ */
+
+/** @typedef {import('../../core/tui/draw.js').Draw} Draw */
+/** @typedef {import('../../core/tui/draw.js').Rect} Rect */
+/** @typedef {import('../../core/tui/draw.js').Span} Span */
+/** @typedef {import('../../core/tui/draw.js').Style} Style */
+
+// ── internal ──────────────────────────────────────────────────────────────────
+
+/** @param {Span[]} spans @returns {number} */
+function spanWidth(spans) {
+  let n = 0;
+  for (const s of spans) n += Array.from(s.text).length;
+  return n;
+}
+
+/** @param {string|string[]|undefined|null} v @returns {string[]} */
+function toLines(v) {
+  if (v == null) return [];
+  if (Array.isArray(v)) return v.map((s) => String(s == null ? '' : s));
+  return [String(v)];
+}
+
+/**
+ * Place a vertically + horizontally centered stack of span-lines in `rect`.
+ * Each entry is one line's spans; rows that fall outside the rect are skipped.
+ * @param {Draw} draw @param {Rect} rect @param {Span[][]} lines
+ */
+function centeredStack(draw, rect, lines) {
+  if (!rect || rect.width <= 0 || rect.height <= 0 || lines.length === 0) return;
+  const start = rect.row + Math.max(0, Math.floor((rect.height - lines.length) / 2));
+  lines.forEach((spans, i) => {
+    const row = start + i;
+    if (row < rect.row || row >= rect.row + rect.height) return;
+    const w = spanWidth(spans);
+    const col = rect.col + Math.max(0, Math.floor((rect.width - w) / 2));
+    draw.spans(row, col, spans, rect.col + rect.width - col);
+  });
+}
+
+// ── states ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Loading — paint a SKELETON of where content will land (dim `····` placeholder
+ * rows), not a lone centered "Loading…". The layout is legible before data
+ * arrives. Pair with the host's `⟳ working` chip + a `setStatus('Loading…')`.
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ rows?: number, label?: string }} [opts]
+ *   rows  — how many skeleton rows (default 4); label — optional dim caption below.
+ */
+export function loadingState(draw, rect, opts = {}) {
+  if (!rect || rect.width <= 0 || rect.height <= 0) return;
+  const n = Math.max(1, Math.min(opts.rows ?? 4, rect.height));
+  const snippetLens = [10, 8, 12, 7, 11];
+  for (let i = 0; i < n; i++) {
+    const row = rect.row + i;
+    const label = '·'.repeat(4);
+    const snipLen = Math.min(snippetLens[i % snippetLens.length], Math.max(0, rect.width - 8));
+    /** @type {Span[]} */
+    const spans = [{ text: label, style: { dim: true } }];
+    if (snipLen > 0) spans.push({ text: '  ' + '·'.repeat(snipLen), style: { dim: true } });
+    draw.spans(row, rect.col + 1, spans, rect.width - 1);
+  }
+  if (opts.label) {
+    const below = { row: rect.row + n + 1, col: rect.col, width: rect.width, height: Math.max(0, rect.height - n - 1) };
+    centeredStack(draw, below, [[{ text: opts.label, style: { dim: true } }]]);
+  }
+}
+
+/**
+ * Empty — the reward state. A small centered stack: a green `✓`, a default-weight
+ * headline, then dim secondary lines. Inbox-zero is a reward, not a void.
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ glyph?: string, headline?: string, secondary?: string|string[] }} [opts]
+ */
+export function emptyState(draw, rect, opts = {}) {
+  const glyph = opts.glyph ?? '✓';
+  const headline = opts.headline ?? 'All caught up';
+  /** @type {Span[][]} */
+  const lines = [
+    [{ text: glyph + '  ', style: { fg: '32' } }, { text: headline }], // green glyph + default headline
+    [{ text: '' }],
+  ];
+  for (const t of toLines(opts.secondary)) lines.push([{ text: t, style: { dim: true } }]);
+  centeredStack(draw, rect, lines);
+}
+
+/**
+ * Error — a centered error block, used ONLY when there is no last-known content
+ * to keep (on a refresh error with a still-good view, raise a banner instead).
+ * `✗` + headline in red/bold, the cause in default weight, a dim retry hint.
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ headline?: string, cause?: string|string[], hint?: string }} [opts]
+ */
+export function errorState(draw, rect, opts = {}) {
+  const headline = opts.headline ?? 'Something went wrong';
+  const cause = toLines(opts.cause);
+  const hint = opts.hint ?? 'Press g to retry.';
+  /** @type {Span[][]} */
+  const lines = [
+    [{ text: '✗  ', style: { fg: '31', bold: true } }, { text: headline, style: { fg: '31', bold: true } }],
+    [{ text: '' }],
+  ];
+  for (const t of cause) lines.push([{ text: t }]);
+  if (cause.length) lines.push([{ text: '' }]);
+  if (hint) lines.push([{ text: hint, style: { dim: true } }]);
+  centeredStack(draw, rect, lines);
+}
+
+/**
+ * Not-ready / guided takeover — the full-content recovery substrate (design §5).
+ * A centered stack: a state glyph (its hue passed by the caller, mono-safe via
+ * the glyph itself), a bold headline naming the state, a dim explanation, and the
+ * explicit next step (an auto-progress note the view writes, or a key to press).
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ glyph?: string, glyphFg?: string, headline?: string, explanation?: string|string[], nextStep?: string }} [opts]
+ *   glyphFg — NUMERIC SGR code for the glyph hue (e.g. '36' cyan working, '31' red blocked).
+ */
+export function notReadyState(draw, rect, opts = {}) {
+  const glyph = opts.glyph ?? '⊙';
+  /** @type {Style} */
+  const glyphStyle = opts.glyphFg ? { fg: opts.glyphFg, bold: true } : { bold: true };
+  const headline = opts.headline ?? 'Not ready';
+  /** @type {Span[][]} */
+  const lines = [
+    [{ text: glyph + '  ', style: glyphStyle }, { text: headline, style: { bold: true } }],
+    [{ text: '' }],
+  ];
+  for (const t of toLines(opts.explanation)) lines.push([{ text: t, style: { dim: true } }]);
+  if (opts.nextStep) {
+    lines.push([{ text: '' }]);
+    lines.push([{ text: opts.nextStep }]); // default weight — the call to action
+  }
+  centeredStack(draw, rect, lines);
+}