Roadmap

Kept so the next session — or the next person — starts with the context rather than the archaeology.

Docs versioning follows create-pleyn (the product entrypoint).

Package	Version
create-pleyn	0.1.0
htmx-contract	0.1.0

Decisions already made

The name is PLEYN, Middle English for plain. Chosen after cairn and create-cairn turned out to be taken on npm, and after discovering that every common English word is gone from that namespace — spare, stark, quiet, slab, folio, wedge, terse, bare, legible, all of them. That is why Vite, Astro, Hono, Zod, Bun, Qwik and Svelte are coined, foreign or deliberately misspelled: it is the only space left. pleyn, create-pleyn and pleyn-stack were all verified free.

The library keeps its descriptive name, htmx-contract, not @pleyn/contract. It is the thing that will bring people to the stack rather than the other way round: somebody searching npm for htmx tooling will find htmx-contract and has no reason ever to search for “pleyn”. It also works with any htmx backend, so hiding it inside an unknown brand costs it its natural audience.

One repository, three parts. The library, the CLI and the template live together, because the template is the only honest test of the other two, and splitting them means keeping three things in step by hand.

The primary artifact is the CLI, not the doctrine. bun create pleyn my-app has to leave a running application: installed, migrated, seeded, styled. A stack whose first experience is a list of setup steps is a blog post.

Single-tenant by default. Users, sessions and one worked resource. Workspaces, roles and installation administration are a decision an application makes, not one a template should make for it.

The template is a workspace member. htmx-contract: ^0.1.0 then resolves to the local package here and to npm in a generated project — one spelling, both cases — and CI can run the template as an application rather than compiling it and hoping.

Done

• htmx-contract extracted with git subtree split, so the commits that explain why each rule exists came with it. Generalised: every trace of the application it came from is gone, and the regression tests were reframed around the shape that causes each failure rather than the incident that exposed it. scripts/no-leaks.ts is wired into CI.
• templates/app — a real application: sessions stored as digests, argon2id via Bun.password, CSRF derived from the session, and a tasks resource with a list, a filter in the query string, an empty state, an out-of-band counter and toasts.
• packages/create-pleyn — copies, substitutes the name, generates a SECRET_KEY, installs, provisions Postgres, waits for it to accept connections, migrates, seeds and builds the stylesheet.
• This documentation site — Starlight under apps/docs, with generated fragments and a mandatory CI job.

Next

1. Publish htmx-contract to npm. Everything else is blocked behind it: until it resolves, bun create pleyn cannot install. Publish from GitHub Actions with --provenance.
2. Publish create-pleyn. bun create pleyn maps to the create-pleyn package; prepack bundles the template into it.
3. A hosted demo, so the claim can be seen rather than read.
4. A lint rule for the db.execute<T>() trap — see Pitfalls.
5. Fill the documentation stubs left intentionally for the next pass.