You set up and run the user's dashboard by driving the zframes CLI and writing a spec. The CLI is the runtime: it serves a prebuilt dashboard app pointed at that one file, editable in the browser. You only ever write JSON. Never create or edit files for this task.

Three jobs, one skill — serve, update, or create. Decide which the request is before anything else (step 1). "Start / open / serve my dashboard" just serves the one the user already has — the most common ask once a dashboard exists — and skips the interview and entirely. Only the create path runs the full build below.

The runtime ships as the CLI on npm. Always invoke it with

npx --yes zframes@latest <cmd>

— npx fetches the published CLI (which bundles the dashboard runtime) per run, so there's nothing to clone, install, or keep current. The commands you'll use below are , , , , and (written for brevity — always run them through ).

Classify the ask first; it decides everything below — including which reference files you read. Only one of the four jobs builds anything; never run the interview or unless you're genuinely creating a dashboard the user doesn't have yet.

The only artifact is a single . There is no app to scaffold — the runtime comes from the CLI. Dashboards live in a global store (, default ), so the user can run from anywhere and keep several side by side, each addressed by a short name (, , …). shows them all, the marking the one a bare will open.

To create one, give it a name and it into the store — don't hand-write the envelope:

npx --yes zframes@latest init <name> --title "<dashboard title>" --author "<who>"

A bare token like lands in the store as and becomes the default if you don't have one yet (so a later bare opens it; pass to force it). This writes a bare, already-valid dashboard — the fixed envelope, modelled on package.json: (semver string), , (pass if the user gave a name, else it's left blank), then the 12-column (geometry — columns/rowHeight/), the unicorn , the colours (/ for the accent + / for the dark card-surface tint + / for gain/loss), the ( sans/mono/serif + proportional/tabular + global text size), the card-surface (////), and the display ( by default) — with an empty

frames

array. You never author that boilerplate or its geometry by hand; you only fill in (step 4). That single file is everything the user owns; sibling files it references (a local image) live next to it in the dashboard's own folder, so each dashboard's assets stay isolated. refuses to clobber an existing file unless you pass .

(Prefer a plain file over the store? Pass a path — or — and every command takes that path too. A token with a or a suffix is always a path; a bare token is always a store name.)

The catalogue is read in two phases — the full dump (~270 frames of JSON Schema, ~400 KB) is far too big to read whole, and you don't need most of it.

Phase 1 — browse. Before choosing anything:

npx --yes zframes@latest catalogue --summary > /tmp/zframes-summary.txt

Read that file fully (~45 KB of plain text): every frame as one line grouped by category, the category taxonomy, and the design vocabulary — the named theme presets with the exact spec values to write and the background scenes with their s. This is the menu you curate frames and cosmetics from in step 4.

Phase 2 — fetch the schemas you'll actually use. Once the design pass has picked the frame set, get the full entries — config schema plus each frame's designed size and resize floor (: ////…) — for exactly those frames:

npx --yes zframes@latest catalogue price-liveline price-chart yield-curve ... > /tmp/zframes-frames.json

Then read the file with your file reader — redirect to a file rather than reading piped stdout, so nothing truncates. Frame names, config fields, enum values, and sizes come from here — never from memory. The catalogue grows; your memory doesn't. An unknown frame name makes the command exit 1 with the valid list — that's your typo feedback, same as lint.

On the create path, interview the user before building — but read

references/interview.md

before asking anything. It holds the whole funnel: a three-round narrowing (asset class → categories → 3–5 specific tickers, with one optional theme-preset question riding along), the option menus per asset class, and the xyz symbol reference that maps every category to the tickers the dex actually carries. The interview picks symbols and (optionally) a look — never frames; you assemble the board yourself in step 4.

Fill the array of the file scaffolded (or the existing file for updates). This is a design job, not a dump, and

references/design.md

is the method — read it before writing any frame JSON. It covers the three passes (4a apply ONE theme preset, 4b curate 20–35 cards in 3–5 zones from a mandatory spine, 4c compose the layout — catalogue sizes, rows packed to 12, headed zones, hierarchy, small asset-logo tiles as decoration and row fillers) plus the card-level fields you'll need while writing: event annotations, clusters, pinning a frame to a second venue with , and per-board/per-card display currency.

npx --yes zframes@latest lint <name>   # the store name (or a path to a dashboard.json)

If it reports issues, fix the JSON and re-lint until clean. The error messages name the frame instance and the exact field. Unknown frame names come back with the list of valid ones — use it. Lint also enforces the design floor: a frame placed under its minimums, overlapping cards, a group child overflowing its group's own /, and a group-in-a-group all fail with the offending numbers named.

Renderer-level failures (a frame whose capability no provider covers) show up as error cards in the running dashboard; treat those the same way.

Serve the dashboard and open it in the user's browser — a printed link is not a hand-off. blocks, so background it (a background shell, a multiplexer window — whatever your harness has), wait for the port to answer, then open the URL:

npx --yes zframes@latest serve <name>   # background this; the store name (or a path)
until curl -sf http://localhost:37263 >/dev/null; do sleep 1; done
open http://localhost:37263             # macOS · xdg-open on Linux · start on Windows

Always write and open the URL as

http://localhost:37263

, never the bare IP — that's what the CLI prints and what the user expects to click. Poll the port rather than sleeping blind: opening before the server binds lands the browser on a connection error. If you passed , open that port.

Live data is installed once, not assumed. A bare install ships no data providers: it renders plainly-simulated demo numbers, badges the header "demo data", and says so at startup. Before the first serve on a machine (or whenever prints the demo notice / the header shows the badge), install the free keyless fleet:

npx --yes zframes@latest providers add keyless   # one-time; prints what it contacts + where the terms live

That printout is the point — it is the user's consent surface, so let it show rather than suppressing it. lists what's installed. (An older published CLI without this command always streams live data — if errors as unknown, just serve.)

hosts the prebuilt runtime pointed at that dashboard, streaming live keyless data once the fleet is installed. A bare (no name) opens the default store dashboard, and when the store holds several the header title becomes a dashboard chooser — the user opens it, picks another, and the page reloads into it, no restart. The user can drag, resize, add, and configure frames in the browser — Save writes the changes straight back to . Edits to the file (yours or theirs) show on reload, so further "add X to my dashboard" requests are just another edit + the page reloads. Pass if 37263 is taken.

Verify it renders designed, not just valid. Lint proves the JSON; it can't see pixels. After serving a newly built or reshaped board, if you have a browser tool, open and sweep once for: error cards ("Invalid configuration", "Unknown frame", missing-capability), cards stuck empty, rows with holes, and clipped card interiors — fix the spec and reload. A "demo data" pill in the header is not a bug: it means no data providers are installed — run and restart the serve. (Give live data a few seconds to settle before judging a card empty; a chart's draw-in animation is not a bug.) No browser tool? Tell the user exactly what to glance for and fix what they report. Skip this sweep for a plain serve or a one-field update — the diff is the proof there.