Quickstart

From a fresh clone to your own exported prototype. The first section takes about a minute of commands; the rest explains what you just did.

The 60-second path

git clone https://github.com/DailybotHQ/protoyard.git
cd protoyard
corepack enable          # uses the pnpm version pinned in package.json
pnpm install
pnpm dev                 # gallery at http://localhost:4321/

The gallery also serves selected public guides under /docs/.

In the gallery, open Pipeline CRM and press Start Pipeline CRM, then Open. Or skip the gallery and run one prototype directly:

pnpm protoyard dev crm-demo

Catalog blueprints and prototypes that include a blueprint.json also offer Open in player on their gallery detail pages. It opens the validated blueprint in the hosted browser player using a share link; entries without a blueprint source keep their existing preview and open actions.

Then, in the running app:

1. Create a deal. Reload the page. It is still there.
2. Press Ctrl + . (⌘ + . on macOS) to open the DevTools panel.
3. Personas tab: switch to Priya Shah (sales rep). Deals owned by other

people can no longer be edited.

1. Scenario tab: load Mature company, year one. Confirm. The world is

rebuilt from its seed.

1. Snaps tab: save a snapshot, change something, restore the snapshot.

Make your own and ship it:

pnpm protoyard new my-idea --template blank
pnpm protoyard dev my-idea
pnpm protoyard validate my-idea
pnpm protoyard export my-idea      # → artifacts/my-idea/my-idea.zip
pnpm protoyard preview my-idea     # serves the static build locally

Requirements

Old Corepack? Very old global Corepack builds (for example 0.10) can't start pnpm 11 and fail with ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING. Update it with npm install -g corepack@latest && corepack enable, or install pnpm directly with npm install -g pnpm@11.

pnpm protoyard doctor --offline checks all of this without touching the network:

Protoyard doctor
✓ Node.js                        v26.11.1 (needs ≥ 24.20.0)
✓ pnpm                           11.23.0
✓ Workspace layout               /…/protoyard
✓ Dependencies                   installed
✓ Templates                      blank, mobile-app, dashboard, …
…
- Cloudflare Pages               CLI not installed (only needed to publish there)

Provider CLIs (Wrangler, Netlify, Vercel) are optional. You only need them to publish (see PUBLISHING.md).

What pnpm dev starts

pnpm dev runs pnpm protoyard gallery, which does three things:

✓ Indexed 82 projects · control server http://127.0.0.1:4300
  Gallery: http://localhost:4321/ (starting…)

Change the ports with pnpm protoyard gallery --port <p> --control-port <p>. The gallery never compiles prototype code. Each prototype runs in its own Vite dev server, started on demand (default port 5173, or the next free one). Why the control server is safe on your machine: ADR-013 in DECISIONS.md.

pnpm protoyard dev <slug> skips the gallery and starts only that prototype:

✓ Pipeline CRM is running at http://localhost:5173/
  Only this prototype is served. Ctrl+C to stop.

Add --host to also print a LAN URL for testing on a phone.

A tour of a running prototype

Everything below happens in the browser. Nothing is sent to a server.

Every value in DevTools shows where it comes from: override, preference, scenario or default. The header's Reset N button clears all temporary overrides.

The first three demos run on the same engine with no shared domain code (the root README lists all 15):

Create your own prototype

pnpm protoyard list --kind template        # what you can start from
pnpm protoyard new my-idea --template blank --name "My Idea"

✓ Created prototypes/my-idea from template blank (23 files)
✓ Linked into the workspace (pnpm install --…)

Next steps:
  pnpm protoyard dev my-idea
  pnpm protoyard validate my-idea
  pnpm protoyard build my-idea

What new does:

• Copies templates/<template>/ into prototypes/<slug>/ (never

node_modules, dist or symlinks), through a staging folder, so an interrupted run leaves nothing half-copied.

• Rewrites the identity: id: "local.<slug>", slug, name,

storage.namespace: "<slug>", template, package name @prototype/<slug>.

• Runs pnpm install to link the new package (--no-install skips it; then

run pnpm install yourself before dev).

• In a consumer workspace, resolves starters from the installed

@protoyard/templates package and replaces every copied workspace: dependency range with the CLI's exact package version. --from <prototype> applies the same rewrite. Monorepo templates and their workspace ranges stay unchanged.

• Refuses to overwrite anything. Re-running the exact same command resumes

safely.

--template is required. Slugs are lowercase kebab-case, 2–48 characters, and some names are reserved (app, docs, gallery, src…).

templates/blank is the smallest complete example (a Notes list with owner and viewer personas). Its README shows how to add a table, a service, a screen and a scenario.

Other starting points

Open the gallery's Marketplace (pnpm dev → /marketplace/) to try every product type. Use this template and Remix create the prototype for you when the gallery runs with pnpm dev:create (it turns on the control server's create endpoint, see SECURITY); otherwise they show the exact pnpm protoyard new command.

Every template is a working app with scenarios, tests and a spec (AGENTS.md + docs/), and runs as a live demo with pnpm protoyard dev <template> (its own template-demo-<name> storage):

For a compact blueprint starter, browse the quick blueprint catalog. It lists the archetype, lazy kits, generated route scope and a validation exercise for each example.

Other ways to start:

pnpm protoyard new my-bank --from mobile-banking-demo          # remix a prototype (fresh id and storage)
pnpm protoyard list --kind blueprint                           # the 40 product blueprints
pnpm protoyard generate my-crm --blueprint blueprints/crm.json  # an app from a data-only blueprint
echo "A salon that books appointments" \
  | pnpm protoyard blueprint new tmp/salon.json --from-brief - --generate salon-demo   # from a prose brief

For an idea you want to try before creating a full project, make a disposable player exploration from a brief or a blueprint:

# Optional in this repository: quick builds the player on first use (about 10 s).
pnpm --filter @protoyard/player build
pnpm protoyard quick "A booking app for a fictional climbing gym" --slug gym-bookings --seed 7 --variants 3
pnpm protoyard quick serve gym-bookings --open

quick serve opens the exploration over 127.0.0.1 until Ctrl+C; with --variants 3 it also wrote v1/…v3/ and a compare.html to view them side by side. The command writes to .protoyard/quick/<slug>/ without building a prototype; the player uses simulated data in the browser. quick.json stores the source brief by default, so use --no-store-brief if that copy is unnecessary and inspect the blueprint before sharing or hosting the folder. The server is bound to loopback only. See the quick skill for supported options, planned workflow features, and the current path to promote an exploration.

helpdesk-demo shows where a generated prototype can go: a blueprint-built CRUD core plus an owned SLA dashboard and ticket workspace (GENERATOR.md). harbor-dispatch-demo, cadence-studio-demo and pulse-revenue-demo are generated with board, calendar, map, timeline, analytics and dashboard screens declared in their blueprints. The brief workflow and its limits are in BRIEF_TO_PROTOTYPE.md.

New prototypes start with a spec. After you change the schema, policy, scenarios or routes, run pnpm protoyard spec my-idea --write to refresh its generated regions (SPECS.md).

A workspace of your own: create-protoyard

create-protoyard scaffolds a Protoyard workspace outside this repository. Nothing is published to npm yet, so npm create protoyard and pnpm create protoyard do not resolve today. Until the first release, run the scaffolder from this repository:

node packages/create-protoyard/bin/create-protoyard.mjs ../acme-lab --no-install --no-git

--no-install is needed for now, because the workspace pins protoyard@<this version>, which npm does not have yet. After the first release the same command becomes:

npm create protoyard acme-lab        # or: pnpm create protoyard acme-lab
cd acme-lab && pnpm protoyard dev starter

It writes:

• package.json, pinning protoyard to the scaffolder's own version (lockstep)

and carrying the workspace marker the CLI looks for ("protoyard": { "workspace": 1 });

• pnpm-workspace.yaml (pnpm) or workspaces (npm) for prototypes/*;
• tsconfig.base.json, which template tsconfigs extend;
• AGENTS.md, README.md and .gitignore;
• a starter prototype in prototypes/starter, made by the CLI's own

protoyard new from @protoyard/templates, with exact package versions and no workspace: ranges.

How it behaves:

• Atomic: everything is staged in a hidden folder next to the target and

renamed into place, so a failure leaves no target and no staging folder.

• Never overwrites: the target must be new or empty. A folder with files, a

plain file, a symlink, the filesystem root or your home folder is refused.

• Install and git: then <pm> install (network) and git init run in the

new folder. With --no-install --no-git no tool runs and nothing touches the network.

Flags:

• --template <name> (default blank) and --pm pnpm|npm, defaulting to the

manager that ran create, else pnpm.

• --yes skips the confirmation on a terminal, and --json prints one

envelope.

• --skill only reports how to install the agent skill

(SKILL); nothing is installed.

• Exit codes: 0 created, 1 failed or not empty, 2 usage or unsafe path,

3 unknown template.

Check, build, export, preview

pnpm protoyard validate my-idea            # manifest, folder contract, scenarios, schema version, svelte-check
pnpm protoyard validate my-idea --build    # …plus a production build
pnpm protoyard build my-idea               # → artifacts/my-idea/dist + build-manifest.json
pnpm protoyard export my-idea              # build + isolation check + ZIP
pnpm protoyard preview my-idea             # http://127.0.0.1:4173/, like a static host
pnpm vitest run prototypes/my-idea         # the prototype's own tests

Real output for the CRM demo, captured on 2026-10-20 (sizes, counts and times change as the workspace grows; most of the 412 files are the fictional avatar images):

$ pnpm protoyard validate crm-demo --skip-typecheck
Validating crm-demo
✓ protoyard.json schema  example.crm v0.1.0
✓ Folder contract files
✓ No symlinks leaving the folder
✓ package.json
✓ Marketplace catalog  sales · CRM
✓ storage.schemaVersion  v2
✓ Scenario ids  9 scenarios
✓ defaultScenario  growing-team
✓ Database versions  v1, v2
✓ Theme ids  violet
✓ Prototype spec (AGENTS.md, docs/)  6 files, 10 generated regions current
- svelte-check
    --skip-typecheck

crm-demo is valid.

$ pnpm protoyard export crm-demo
…
✓ Exported crm-demo
  artifacts/crm-demo/crm-demo.zip  1.1 MB  (412 files)
  sha256 63b5739c…
  Isolation: no references to the other 81 registered projects.
  Relocatable (base ./): unzip into any folder of any static host.

Builds exclude DevTools and show a small "Prototype · simulated data" badge. Both are configurable. Hosting and publishing are covered in PUBLISHING.md.

Everything as one site: the showcase

pnpm build:showcase      # = pnpm protoyard showcase → artifacts/showcase/
pnpm preview:showcase    # = pnpm protoyard showcase --skip-build --serve (port 4500)

The showcase is one static site: the gallery and marketplace, plus a live demo of every prototype (p/<slug>/app/) and every template (t/<name>/app/, unless --no-templates). It needs no control server, so it can be hosted anywhere static. It builds every project, so it takes longer than one prototype. Details, --publish cloudflare and GitHub Pages: PUBLISHING.md.

Scripting the CLI

Every command accepts --json and prints one envelope on stdout:

pnpm protoyard list --json | jq '.data.entries[].slug'

{ "ok": false, "command": "validate",
  "error": { "code": "not_found", "message": "No prototype folder prototypes/does-not-exist.",
             "hint": "Run `pnpm protoyard list` to see the available prototypes." } }

Exit codes: 0 ok · 1 failure · 2 usage · 3 not found · 4 validation · 5 provider/auth. Details and agent workflows: AGENT_GUIDE.md.

Where to go next