# Tell a visual thought, then continue

Storyboard is a surface for you, the existing agent, to explain and think with a person. Do not ask them to select a demo topic if you already have something worth explaining. Say why a visual surface will help, then drive the explanation. No second model lives in the bridge.

Read [the component reference](COMPONENTS.md) before authoring. This guide and the runtime must come from the same kit version.

## Start without asking the person to manage a server

Locate this kit's `cli.mjs`: in a distributed skill it is `runtime/cli.mjs` beside this guide's directory; in the source repository it is two directories above this guide. Use an absolute CLI path so workspace changes don't select a different kit. Let `KIT` be its containing directory and `WORKSPACE` the approved working directory.

Check Node 22+; do not silently install tools or change global configuration. Explain any local download/execution effects if the host requires approval. The kit has no runtime dependency install or build step.

```sh
node "$KIT/cli.mjs" ensure --workspace "$WORKSPACE"
```

This checks a matching instance, chooses an available loopback port for a new one, verifies health, and returns JSON. It does not use or stop an unrelated listener. State and logs live below `$WORKSPACE/.storyboard/`. Sessions and drafts contain plaintext human input; do not publish them.

Write the first completed thought to `opening.json` as `{title,units}`. Prefer a short premise, not the entire eventual explanation. Files should live in an approved workspace, preferably ignored local trial storage when they contain personal material.

```sh
node "$KIT/cli.mjs" open --workspace "$WORKSPACE" --file opening.json
```

Share the returned URL as a non-final progress message, then immediately continue authoring or waiting. The URL points to the bridge's computer, not automatically the person's laptop if you're remote. Do not claim access without checking the local arrangement. Do not expose the bridge publicly.

## Speak completed thoughts progressively

**Publish each useful completed visual thought as soon as it is ready. Do not finish composing the whole explanation before your first update.**

A good sequence is a premise, a meaningful contrast, then a flow that explains why. Publish those separately as you author them. Do not send partial JSON, token-by-token diagram fragments, artificial pauses, or a spinner in place of actual thought. Don't fragment content so finely that the page jitters.

Choose representation by purpose:

- Prose for meaning; comparison for aligned differences.
- Flow for directed relationships; annotation for the important interpretation.
- Prompt for a response that will change what comes next.

Use the reference's bounds and counterexamples. Keep captions and node details short. Prefer a few clear units to exhausting the component catalog. Motion is owned by trusted renderers; no agent-authored animation code is needed.

For each next completed thought, write an edit array and publish it:

```sh
node "$KIT/cli.mjs" read ID --workspace "$WORKSPACE"
node "$KIT/cli.mjs" edit ID --workspace "$WORKSPACE" --revision CURRENT_REVISION --file edits.json
```

Use stable unit IDs. Add an annotation or replace one relevant unit instead of restating the entire explanation. Use `after` for placement. A stale revision requires rereading and reconciliation. An ambiguous write requires read-back, not blind replay.

## Make input part of the explanation

Place a prompt with the thought it addresses. Ask for reasoning where it could reveal a misconception or a constraint. The answer stays in context. Stored input is not agent acknowledgement; publish a real responsive thought to acknowledge it.

Agree a finite answer window and number of adaptations with the person. Parameterize these separately, for example `ANSWER_WINDOW_SECONDS=180`, `EVENT_WAIT_SECONDS=30`, and one responsive adaptation. Keep a fixed deadline measured from URL delivery or the agreed start; empty waits do not reset it. Only an explicit user request resets the window.

```sh
node "$KIT/cli.mjs" wait ID --workspace "$WORKSPACE" --after LAST_HANDLED_EVENT --wait SECONDS
```

Choose each wait no longer than the remaining answer window and at most 300 seconds. Fit the CLI wait plus its 10-second network margin inside the host timeout. The server holds the request and responds when input arrives; 30 seconds is a maximum wait, not a delivery delay.

Consume foreground results. A successful `{ "events": [] }` renews with the same cursor while budget remains. Host timeout/error is different: inspect the pending process and read state/events before recovery, without duplicate waiters or uncertain write replay. Background waiting is only acceptable when completion delivery and agent resumption have been verified. Do not finalize while claiming to remain engaged.

Read the actual `promptId`, `promptRevision` and `values`. First publish a concise useful response to that reasoning. Then refine the relevant comparison, flow or annotation as another completed thought. Do not congratulate and repeat the answer. Do not label an interpretation a misconception unless the actual reasoning supports it.

An explanatory edit can occur while the person drafts; it must not replace an unrelated prompt. Changing a question changes its definition version, requiring an explicit draft handoff in the browser. Use a new prompt ID for a new turn, not a mutation that reinterprets an old answer.

Advance the handled event cursor only after the requested responsive edits are confirmed. Stop at the agreed bound, cancellation, completion or a material limitation. Further questions on the canvas do not mean you remain monitoring after a final reply.

## Finish honestly

Read back the committed state. Ask the person whether the already-open canvas updated, whether the adaptation helped, and whether the experience felt responsive. Automation is not human acceptance. Preserve the tested revision, kit identity, exact wait results and remaining limits without publishing private links/input.

The owned bridge may remain available for the open canvas. If stopping it is appropriate and within the agreed lifecycle, use:

```sh
node "$KIT/cli.mjs" stop --workspace "$WORKSPACE"
```

This verifies the saved instance and owner token, waits for shutdown and preserves state. It is not a command to kill whichever process happens to hold a port. Never delete live writer locks, user drafts or session data to force startup.
