Compose & run

A Chord project has four everyday commands: build, play, test, and compose. All of them run from the project directory.

Build: including a playable web page

sharpee build

🔨 Building browser bundle

  ✓ Validated orchard.story (gate-clean) — source not shipped (`publish-source:` absent)
  ✓ Story IR → dist/orchard.ir.json
  Bundling game.js...
  ✓ Built game.js
  ✓ Copied index.html
  ✓ Copied platform engine CSS (base, engine, decorations)
  ✓ Copied orchard.css

✅ Build complete! (game.js 1213.1 KB)

Output: dist/web/<id>/

dist/web/<id>/ is a self-contained, static web page: your story, the engine, and a browser client in one folder. Serve it locally with npx serve dist/web/<id>, or host it anywhere static files go. For a .story, the browser client is the default — sharpee build needs no flag. Your source stays out of the bundle unless the story header says publish-source: yes.

Play in the terminal

sharpee play

--- Play Mode ---  (/quit or /q to exit)

orchard

Story v0.1.0

Landing
A quiet place to begin. Doorways lead everywhere a story might go —
for now, this landing is the whole world.

> inventory
You are carrying:

a brass lantern

>

Type commands at the prompt exactly as a player would; /quit exits.

Test with the tree document

Your tests are one file beside the story, <story-id>.tests.json: the turns you played in Chord Writer's Testing tab, each with the claims it recorded about what the story said. sharpee test replays that document fresh from boot at the story's pinned seed:

sharpee test

Tree document: orchard.tests.json (seed 42, 2 line(s))

✓ opening-landing
✓ landing · rub lantern
6 cards passing, 16 assertions passing
8 commands (6 authored + 2 replayed)

Every card and every claim gets a verdict, and sharpee test exits non-zero on any failure, so it drops straight into CI. --stop-on-failure halts at the first miss; --json streams the results for tooling. The document's shape — cards, branches, and the six claim families, including state claims spelled the way the story spells them — is on the sharpee test page. To try commands without recording anything, pipe them into sharpee play: printf 'north\nlook\n' | sharpee play.

Compose: the compiler on its own

build and play compile your story implicitly. compose is the same compiler as a standalone step:

sharpee compose orchard.story --check

compose: orchard.story is gate-clean (--check: IR not emitted)

--check runs every load-time gate and emits nothing, which makes it the fast CI answer to "does my story still compile?". With -o it writes the compiled story IR as JSON:

compose: orchard.story loaded — 3 entities, 0 trait(s), 0 action(s), 0 hatch(es)
compose: IR written to orchard.ir.json

Next

The world model is where stories get interesting. Start with building your world.