Showboat

<essential_principles>

Scope

This skill encodes forgejo-mcp-local conventions for Showboat. It is self-contained — it does not depend on any external recipe skill.

What Showboat Is

Showboat is a CLI (uvx showboat) that builds Markdown "demo documents" that interleave narrative, executable code blocks, and captured output. A demo produced by Showboat is simultaneously a readable story and a reproducible script. Think lab notebook snapshot: the author ran the commands, Showboat captured their output verbatim, and the resulting file is committed as proof.

Core commands — always run showboat --help for the authoritative reference, do not memorize flags:

• showboat init <file> <title> — start a new demo
• showboat note <file> [text] — append narrative text
• showboat exec <file> <lang> [code] — run a command and capture its output
• showboat image <file> <path> — embed an image
• showboat pop <file> — remove the last entry (use when a command errored)

1. One Demo Per Spec, Co-Located

Every implementation PR that closes a spec-linked issue commits a demo file co-located with the spec it proves. The host skill specifies the canonical demo path — follow that convention.

2. Author Builds, Reviewer Reads

The author constructs the demo live against a running instance, captures real output, commits the Markdown. The reviewer does not re-execute. They read the file like a lab notebook during acceptance. Two reasons:

• Environment independence — the reviewer needs no runtime, no deploy step, no showboat install. They read markdown in the PR diff.
• Determinism — structured output typically contains timestamps and generated IDs that drift across runs. showboat verify would diff-fail on every re-run. We do not run verify on the critical path today.

3. Trust the Author at Commit Time

No automation re-executes the demo. The contract: the author ran the commands and committed the real captured output. Hand-writing an output block to hide a failure is a skill violation.

Retrofit exception: A retrofitted demo may commit placeholder output blocks (# TODO: re-run against live instance) where real output is stale or unavailable. The placeholder is explicit — it documents a gap, not hides a failure.

4. Demo Through the Project's Structured Surface

Prefer subcommands that emit structured output (JSONL or similar) over raw database queries, raw runtime RPCs, or arbitrary shell.

If you cannot demonstrate an acceptance criterion through the project's instrumented CLI, that is a missing subcommand in the project's observability contract — not a showboat problem. Stop, add the subcommand in the same PR, then resume the demo.

5. One Section Per Acceptance Criterion (non-anchored specs)

For non-anchored specs the narrative maps 1:1 to the spec's acceptance list:

• One showboat note anchoring the criterion (heading + paraphrase)
• One or more showboat exec blocks producing evidence
• No criterion without evidence; no stray evidence without an anchor

For anchored specs (with <!-- demos-anchored: true -->), the 1:1 mapping is by #### Scenario: heading instead — see anchored-mode.md.

</essential_principles>

<mode_dispatch>

Mode Dispatch

Read the sibling spec.md first. Then choose:

Before authoring in any mode, scan authoring-smells.md — the seven antipatterns there apply universally.

</mode_dispatch>

<intake>

Required inputs, supplied by the host skill:

• Spec path — the spec file whose acceptance criteria the demo will prove
• Demo path — the co-located output path convention (e.g. <spec-dir>/<slug>.demo.md)
• Running instance — the branch under review, deployed and reachable
• Project CLI — the instrumented subcommand surface the demo should use

For retrofit mode, the running instance is optional (placeholder output is acceptable). For new anchored or non-anchored demos, it is required.

If any required input is missing, ask before proceeding.

</intake>

<workflow>

Portable Binary Reference (path portability)

Never embed absolute paths to a local build in evidence commands. Use the env-var pattern and document the setup at the top of the demo:

## Replay setup

```bash
export FORGEJO_MCP_BIN="${FORGEJO_MCP_BIN:-forgejo-mcp}"
# Point at a local build: export FORGEJO_MCP_BIN=./forgejo-mcp
```

Then reference the binary as ${FORGEJO_MCP_BIN} in all evidence commands. For arbitrary repo-rooted scripts, use ${SHOWBOAT_REPO:-$(git rev-parse --show-toplevel)}. See authoring-smells.md smells #1 and #7.