Write Wizard

A browser tool that walks a developer through their PowerSync stack and hands them a prompt to run in their own coding agent, which generates a working client-and-backend example.

The Wizard never generates code itself — see docs/adr/0001-wizard-emits-a-prompt.md.

Running it

pnpm install
pnpm dev

Checks

pnpm test        # unit tests
pnpm typecheck   # tsc --noEmit
pnpm build       # static SPA bundle, entry route prerendered

Running it yourself

There is no hosted instance, by choice — see docs/adr/0005-no-hosted-instance.md. You run it yourself, and that is the only way it is meant to be used.

The Wizard is a static site with no server, no API and no configuration. There is nothing to provision and nothing to keep secret.

git clone <this repo> && cd write-wizard
pnpm install --frozen-lockfile
pnpm build            # writes dist/client
pnpm preview          # or serve dist/client with any static file server

Copy dist/client to whatever serves static files — S3, nginx, GitHub Pages, a CDN, a USB stick. Two things make this easier than it usually is:

• No rewrite rules. There is one route, /, and a run's choices live in the query string rather than the path. A host that serves index.html at / is enough; you do not need SPA history fallback.
• No build-time configuration. No API keys, no base URL, no environment variables. The Contract and the Capability Briefs are bundled into the JavaScript, so an emitted Prompt is complete even with the network off.

Handover is one code path: clipboard and download both take the already-assembled Prompt text, so the two cannot hand over different things.

Keeping up with upstream

pnpm regenerate                                    # needs an authenticated `gh`
WIZARD_REFERENCE_REPO=owner/repo pnpm regenerate   # if the reference has moved

Mirrors the three things the Wizard depends on but does not own — the maturity badges, the raw pull request prose the Capability Briefs were authored from, and the Contract — and reports what moved. Nothing is written unless every fetch and parse succeeds, and a parse miss exits non-zero.

It rewrites the badges and the raw prose. It never rewrites the authored Briefs in src/wizard/briefs/, and never applies a changed Contract — both are reported for a human to act on. See docs/adr/0004-mirror-upstream-prose.md.

Where things are

• CONTEXT.md — the domain glossary. Capitalised terms in code and docs mean what it says there.
• docs/adr/ — decisions that were hard to reverse, and why.
• .scratch/wizard-design/spec.md — the confirmed design, and its open items.
• .scratch/wizard-design/issues/ — the ticket queue.