create-minlang-app 0.2.0 → 0.4.0

package/bin.mjs

@@ -37,6 +37,7 @@ substitute(dest);
 renameSync(join(dest, "__APP_NAME__.ml"), join(dest, `${name}.ml`));
 // npm strips dotfiles from published packages; restore them.
 renameSync(join(dest, "gitignore"), join(dest, ".gitignore"));
+renameSync(join(dest, "gitattributes"), join(dest, ".gitattributes"));
 renameSync(join(dest, "github"), join(dest, ".github"));
 
 // .github/ only works at the repository root: warn when the scaffold is
@@ -64,7 +65,7 @@ Next steps:
   pnpm --dir app install
   make dev               # http://localhost:3111
 
-Your whole app lives in ${name}.ml (it starts as a task tracker — replace it).
+Your whole app lives in ${name}.ml (it starts as a MinLang welcome tour — replace it).
 Agent instructions: ${name}/AGENTS.md
 Language rules: https://github.com/codeshift-ai-solutions/minlang-releases/releases/latest/download/minlang-language-bundle.md
 Deploys: push to GitHub with org secrets VERCEL_TOKEN/VERCEL_ORG_ID set;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-minlang-app",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Scaffold a MinLang web app: write one .ml file, compile with ml1, deploy.",
   "license": "MIT",
   "repository": {

package/template/AGENTS.md

@@ -27,6 +27,17 @@ detector list, and the end-to-end web-app authoring guide. Highlights:
 - Generate -> validate -> fix -> revalidate until zero violations, then
   output. `ml1 validate` is the same gate CI runs.
 
+## Language version & updates
+
+This repo is pinned to a MinLang language version in `minlang.json`
+(`languageBundleVersion`, written by `ml1 init`). Run `make update` (or
+`ml1 update`) to pull a newer compiler + language. When the language has
+moved on, update writes `MINLANG_MIGRATION.md` — a checklist of
+old-form -> new-form recommendations. Read it, apply the changes to
+`__APP_NAME__.ml`, run `make compile && make test` until green, then delete
+it. `ml1 update` advances the pin for additive upgrades and never edits your
+`.ml` itself.
+
 ## Commands
 
 | Task | Command |
@@ -36,9 +47,12 @@ detector list, and the end-to-end web-app authoring guide. Highlights:
 | Compile to `app/generated/` | `make compile` |
 | Install shell deps | `pnpm --dir app install` |
 | Unit + generated test triads | `make test` |
+| Lint custom skins (`app/skins/`) | `make lint-skins` (also runs in `make test`) |
 | Dev server (http://localhost:3111) | `make dev` |
+| Update toolchain, language pin + deps | `make update` (writes MINLANG_MIGRATION.md if the language moved on) |
 | Production build | `make build` |
 | Browser tests (a11y, perf) | `make test-e2e` (installs the browser on first run) |
+| Screen previews (`screen-previews/*.png`, all screens, mobile + desktop) | `make preview` |
 
 `make compile` requires the `ml1` compiler on PATH — install per README.
 If `pnpm typecheck` complains about routes you deleted, remove the stale
@@ -58,3 +72,6 @@ user-facing copy, or input validation in shell code — they belong in
 `__APP_NAME__.ml`, where the validator and generated tests cover them.
 Screens route through the single dynamic page
 `app/app/screens/[screen]/page.tsx`; do not create per-screen folders.
+Custom widget renderers ("skins") go in `app/skins/` — see the Skins
+section of the language bundle; `make lint-skins` enforces the contract
+(no hardcoded copy, no raw colors, no fetch/Date.now/adapter imports).

package/template/Makefile

@@ -1,6 +1,6 @@
 APP := __APP_NAME__
 
-.PHONY: validate compile build test test-e2e dev
+.PHONY: validate compile build test test-e2e lint-skins preview dev update
 
 validate:
 	ml1 validate $(APP).ml
@@ -13,10 +13,21 @@ build:
 
 test:
 	pnpm --dir app run test
+	node scripts/lint-skins.mjs app/skins
+
+lint-skins:
+	node scripts/lint-skins.mjs app/skins
 
 test-e2e:
 	pnpm --dir app exec playwright install chromium
 	pnpm --dir app run test:e2e
 
+preview:
+	pnpm --dir app exec playwright install chromium
+	pnpm --dir app run test:e2e e2e/99-screens.spec.ts
+
 dev:
 	pnpm --dir app run dev
+
+update:
+	ml1 update

package/template/__APP_NAME__.ml

@@ -1,240 +1,174 @@
-entity Workspace {
+// Welcome to MinLang — the starter app `ml1 init` / `npm create minlang-app`
+// scaffolds. The WHOLE app is this one file: entities (data shape),
+// constraints (the only place rules live), actions (pure create/set/delete),
+// queries (read-only view-models), screens (declarative UI + copy), and
+// tests (the success / failure / no-change triad). Edit this file, run
+// `make compile`, and the generated app updates. Delete the demo below and
+// model your own domain when you're ready.
+
+// --- Navigation state -------------------------------------------------------
+// A single Tour row drives which screen is active (see the `when` selectors).
+entity Tour {
 	id: string req
-	view: enum(board, projects)
+	page: enum(welcome, files, enhance, resources)
 }
 
-entity Project {
+// --- A tiny live demo: a guestbook note -------------------------------------
+// Shows the core loop — a form creates a row, a constraint guards it, a board
+// lists it, and tests prove all three.
+entity Note {
 	id: string req
-	name: string
+	greeting: string
 }
 
-entity Task {
+// --- Seeded content shown as tables (rows live in app/seed.ts) --------------
+entity FileGuide {
 	id: string req
-	project: ref(Project)
-	title: string
-	status: enum(todo, doing, done)
-	assignee: string
-	created_at: string
-	actor_id: string
+	file: string
+	purpose: string
 }
 
-constraint TitleRequired {
-	on: Task
-	validate: NOT(self.title == '')
-	message: 'title is required'
-}
-
-constraint AssigneeRequiredWhenDoing {
-	on: Task
-	validate: NOT(self.status == 'doing' AND self.assignee == '')
-	message: 'assignee is required when a task is doing'
-}
-
-constraint ProjectExists {
-	on: Task
-	validate: count(Project as p, p == self.project) == 1
-	message: 'project does not exist'
-}
-
-constraint ProjectNameRequired {
-	on: Project
-	validate: NOT(self.name == '')
-	message: 'project name is required'
-}
-
-constraint UniqueProjectName {
-	on: Project
-	validate: count(Project as p, p.name == name) == 0
-	message: 'a project with this name already exists'
-}
-
-action CreateProject(id: string, name: string, actor_id: string) {
-	on: Project
-	create(Project, { id: id, name: name })
-}
-
-action CreateTask(id: string, project: ref(Project), title: string, status: enum(todo, doing, done), assignee: string, created_at: string, actor_id: string) {
-	on: Task
-	create(Task, { id: id, project: project, title: title, status: status, assignee: assignee, created_at: created_at, actor_id: actor_id })
+entity BuildStep {
+	id: string req
+	step: string
+	detail: string
 }
 
-action MoveTask(id: string, status: enum(todo, doing, done), actor_id: string) {
-	on: Task
-	set(status, status)
+entity Resource {
+	id: string req
+	topic: string
+	link: string
 }
 
-action RenameTask(id: string, title: string, actor_id: string) {
-	on: Task
-	set(title, title)
+// --- Rules live in constraints, never in actions ----------------------------
+constraint GreetingRequired {
+	on: Note
+	validate: NOT(self.greeting == '')
+	message: 'a greeting is required'
 }
 
-action OpenProjects(workspace: ref(Workspace), actor_id: string) {
-	on: Workspace
-	set(view, 'projects')
+// --- Actions are pure mutation (create / set / delete) ----------------------
+action AddNote(id: string, greeting: string, actor_id: string) {
+	on: Note
+	create(Note, { id: id, greeting: greeting })
 }
 
-action OpenBoard(workspace: ref(Workspace), actor_id: string) {
-	on: Workspace
-	set(view, 'board')
+action ShowWelcome(tour: ref(Tour), actor_id: string) {
+	on: Tour
+	set(page, 'welcome')
 }
 
-query TaskBoard(workspace: ref(Workspace)) -> list<Task> {
-	from Task
+action ShowFiles(tour: ref(Tour), actor_id: string) {
+	on: Tour
+	set(page, 'files')
 }
 
-query ProjectList(workspace: ref(Workspace)) -> list<Project> {
-	from Project
+action ShowEnhance(tour: ref(Tour), actor_id: string) {
+	on: Tour
+	set(page, 'enhance')
 }
 
-query TaskDetail(task: ref(Task)) -> Task {
-	from Task
+action ShowResources(tour: ref(Tour), actor_id: string) {
+	on: Tour
+	set(page, 'resources')
 }
 
-screen Board {
-	when workspace.view == 'board'
-	title "Task board"
-	hint "Create tasks, move them between statuses, and rename them."
-	board TaskBoard
-	primary { label "Add task" action CreateTask }
-	button { label "Move task" action MoveTask }
-	button { label "Rename task" action RenameTask }
-	button { label "Projects" action OpenProjects }
+// --- Queries are read-only view-models --------------------------------------
+query NoteList(tour: ref(Tour)) -> list<Note> {
+	from Note
 }
 
-screen Projects {
-	when workspace.view == 'projects'
-	title "Projects"
-	body "Every task belongs to a project."
-	board ProjectList
-	primary { label "Add project" action CreateProject }
-	button { label "Back to board" action OpenBoard }
+query FileList(tour: ref(Tour)) -> list<FileGuide> {
+	from FileGuide
 }
 
-test CreateTaskSucceeds {
-	setup: [
-		create(Workspace, { id: "w1", view: "board" }),
-		create(Project, { id: "p1", name: "General" })
-	]
-	when: CreateTask on Task { id: "t1", project: "p1", title: "Ship the compiler", status: "todo", assignee: "" }
-	then: [
-		entity_count(Task) == 1,
-		entity_has(Task.1, title == "Ship the compiler")
-	]
-}
-
-test TitleRequiredRejectsEmpty {
-	setup: [
-		create(Workspace, { id: "w1", view: "board" }),
-		create(Project, { id: "p1", name: "General" })
-	]
-	when: CreateTask on Task { id: "t1", project: "p1", title: "", status: "todo", assignee: "" }
-	then: [
-		error_raised('title is required'),
-		entity_count(Task) == 0
-	]
+query StepList(tour: ref(Tour)) -> list<BuildStep> {
+	from BuildStep
 }
 
-test AssigneeRequiredWhenDoingRejects {
-	setup: [
-		create(Workspace, { id: "w1", view: "board" }),
-		create(Project, { id: "p1", name: "General" })
-	]
-	when: CreateTask on Task { id: "t1", project: "p1", title: "Ship the compiler", status: "doing", assignee: "" }
-	then: [
-		error_raised('assignee is required when a task is doing'),
-		entity_count(Task) == 0
-	]
+query ResourceList(tour: ref(Tour)) -> list<Resource> {
+	from Resource
 }
 
-test ProjectExistsRejectsUnknown {
-	setup: [
-		create(Workspace, { id: "w1", view: "board" })
-	]
-	when: CreateTask on Task { id: "t1", project: "ghost", title: "Ship the compiler", status: "todo", assignee: "" }
-	then: [
-		error_raised('project does not exist'),
-		entity_count(Task) == 0
-	]
+// --- Screens: declarative flow + copy (all text lives here) -----------------
+screen Welcome {
+	when tour.page == 'welcome'
+	title "Welcome to MinLang"
+	body "The whole app is one .ml file. Edit it, run make compile, and this UI updates."
+	hint "Try the demo: add a note below, then take the tour."
+	board NoteList
+	primary { label "Say hello" action AddNote }
+	button { label "What's in this project" action ShowFiles }
+	button { label "Learn more" action ShowResources }
 }
 
-test MoveTaskSucceeds {
-	setup: [
-		create(Workspace, { id: "w1", view: "board" }),
-		create(Project, { id: "p1", name: "General" }),
-		create(Task, { id: "t1", project: "p1", title: "Ship the compiler", status: "todo", assignee: "casey", created_at: "2026-01-01T00:00:00Z", actor_id: "a1" })
-	]
-	when: MoveTask on Task { id: "t1", status: "doing" }
-	then: [
-		entity_has(Task.1, status == "doing"),
-		entity_count(Task) == 1
-	]
+screen Files {
+	when tour.page == 'files'
+	title "What's in this project"
+	body "Everything is generated from your .ml source. Edit it, never app/generated."
+	board FileList
+	primary { label "How to enhance it" action ShowEnhance }
+	button { label "Back to start" action ShowWelcome }
 }
 
-test MoveTaskRejectsDoingWithoutAssignee {
-	setup: [
-		create(Workspace, { id: "w1", view: "board" }),
-		create(Project, { id: "p1", name: "General" }),
-		create(Task, { id: "t1", project: "p1", title: "Ship the compiler", status: "todo", assignee: "", created_at: "2026-01-01T00:00:00Z", actor_id: "a1" })
-	]
-	when: MoveTask on Task { id: "t1", status: "doing" }
-	then: [
-		error_raised('assignee is required when a task is doing'),
-		entity_has(Task.1, status == "todo")
-	]
+screen Enhance {
+	when tour.page == 'enhance'
+	title "Make it yours"
+	body "Describe your own domain in the .ml, then compile and test."
+	board StepList
+	primary { label "Resources" action ShowResources }
+	button { label "Back to start" action ShowWelcome }
 }
 
-test RenameTaskSucceeds {
-	setup: [
-		create(Workspace, { id: "w1", view: "board" }),
-		create(Project, { id: "p1", name: "General" }),
-		create(Task, { id: "t1", project: "p1", title: "Old name", status: "todo", assignee: "", created_at: "2026-01-01T00:00:00Z", actor_id: "a1" })
-	]
-	when: RenameTask on Task { id: "t1", title: "New name" }
-	then: [
-		entity_has(Task.1, title == "New name")
-	]
+screen Resources {
+	when tour.page == 'resources'
+	title "Learn more"
+	body "The language bundle has the full rules and the web authoring guide."
+	hint "Fetch it: github.com/codeshift-ai-solutions/minlang-releases/releases/latest/download/minlang-language-bundle.md"
+	board ResourceList
+	primary { label "Back to start" action ShowWelcome }
+	button { label "What's in this project" action ShowFiles }
 }
 
-test CreateProjectSucceeds {
+// --- Tests: the success / failure / no-change triad -------------------------
+test AddNoteSucceeds {
 	setup: [
-		create(Workspace, { id: "w1", view: "board" })
+		create(Tour, { id: "t1", page: "welcome" })
 	]
-	when: CreateProject on Project { id: "p1", name: "Platform" }
+	when: AddNote on Note { id: "n1", greeting: "Hello, MinLang" }
 	then: [
-		entity_count(Project) == 1,
-		entity_has(Project.1, name == "Platform")
+		entity_count(Note) == 1,
+		entity_has(Note.1, greeting == "Hello, MinLang")
 	]
 }
 
-test ProjectNameRequiredRejectsEmpty {
+test GreetingRequiredRejectsEmpty {
 	setup: [
-		create(Workspace, { id: "w1", view: "board" })
+		create(Tour, { id: "t1", page: "welcome" })
 	]
-	when: CreateProject on Project { id: "p1", name: "" }
+	when: AddNote on Note { id: "n1", greeting: "" }
 	then: [
-		error_raised('project name is required'),
-		entity_count(Project) == 0
+		error_raised('a greeting is required'),
+		entity_count(Note) == 0
 	]
 }
 
-test UniqueProjectNameRejectsDuplicate {
+test ShowFilesSwitchesPage {
 	setup: [
-		create(Workspace, { id: "w1", view: "board" }),
-		create(Project, { id: "p0", name: "General" })
+		create(Tour, { id: "t1", page: "welcome" })
 	]
-	when: CreateProject on Project { id: "p1", name: "General" }
+	when: ShowFiles on Tour { tour: "t1" }
 	then: [
-		error_raised('a project with this name already exists'),
-		entity_count(Project) == 1
+		entity_has(Tour.1, page == "files")
 	]
 }
 
-test OpenProjectsSwitchesView {
+test ShowWelcomeReturnsHome {
 	setup: [
-		create(Workspace, { id: "w1", view: "board" })
+		create(Tour, { id: "t1", page: "files" })
 	]
-	when: OpenProjects on Workspace { workspace: "w1" }
+	when: ShowWelcome on Tour { tour: "t1" }
 	then: [
-		entity_has(Workspace.1, view == "projects")
+		entity_has(Tour.1, page == "welcome")
 	]
 }

package/template/app/e2e/01-welcome.spec.ts

@@ -0,0 +1,36 @@
+// Core journeys: land on the welcome screen, add a greeting through the demo
+// form, see the rejection path, and confirm the tour screens render their
+// seeded tables. Deterministic: every run starts a fresh server with the
+// same seed.
+
+import { expect, test } from "@playwright/test";
+
+test.describe.configure({ mode: "serial" });
+
+test("welcome screen: add a greeting -> table row", async ({ page }) => {
+	await page.goto("/");
+	await expect(page.getByRole("heading", { name: "Welcome to MinLang" })).toBeVisible();
+
+	const form = page.getByRole("form", { name: "Add note" });
+	await form.getByLabel("Greeting").fill("Hi there");
+	await form.getByRole("button", { name: "Say hello" }).click();
+
+	await expect(page.getByRole("row").filter({ hasText: "Hi there" })).toBeVisible();
+});
+
+test("validation rejection shows the exact constraint message", async ({ page }) => {
+	await page.goto("/");
+	const form = page.getByRole("form", { name: "Add note" });
+	await form.getByRole("button", { name: "Say hello" }).click();
+	await expect(form.getByRole("alert")).toHaveText("a greeting is required");
+});
+
+test("tour screens render their seeded content tables", async ({ page }) => {
+	await page.goto("/screens/files");
+	await expect(page.getByRole("heading", { name: "What's in this project" })).toBeVisible();
+	await expect(page.getByRole("row").filter({ hasText: "app/generated/" })).toBeVisible();
+
+	await page.goto("/screens/resources");
+	await expect(page.getByRole("heading", { name: "Learn more" })).toBeVisible();
+	await expect(page.getByRole("row").filter({ hasText: "Language rules" })).toBeVisible();
+});

package/template/app/e2e/02-a11y.spec.ts

@@ -1,5 +1,5 @@
 // WCAG 2.1 AA gate: axe-core scans per screen (no serious/critical
-// violations) and a keyboard-only create journey.
+// violations) and a keyboard-only "add a greeting" journey.
 
 import AxeBuilder from "@axe-core/playwright";
 import { expect, test } from "@playwright/test";
@@ -14,31 +14,27 @@ const scan = async (page: import("@playwright/test").Page): Promise<void> => {
 	expect(serious, JSON.stringify(serious, null, 2)).toEqual([]);
 };
 
-test("board screen is axe-clean (WCAG 2.1 AA)", async ({ page }) => {
+test("welcome screen is axe-clean (WCAG 2.1 AA)", async ({ page }) => {
 	await page.goto("/");
-	await expect(page.getByRole("heading", { name: "Task board" })).toBeVisible();
+	await expect(page.getByRole("heading", { name: "Welcome to MinLang" })).toBeVisible();
 	await scan(page);
 });
 
-test("projects screen is axe-clean (WCAG 2.1 AA)", async ({ page }) => {
-	await page.goto("/screens/projects");
-	await expect(page.getByRole("heading", { name: "Projects" })).toBeVisible();
+test("files screen is axe-clean (WCAG 2.1 AA)", async ({ page }) => {
+	await page.goto("/screens/files");
+	await expect(page.getByRole("heading", { name: "What's in this project" })).toBeVisible();
 	await scan(page);
 });
 
-test("keyboard-only journey: create a task without the mouse", async ({ page }) => {
+test("keyboard-only journey: add a greeting without the mouse", async ({ page }) => {
 	await page.goto("/");
-	const form = page.getByRole("form", { name: "Create task" });
-	await form.getByLabel("Project").focus();
-	await page.keyboard.press("Tab"); // -> Title
-	await page.keyboard.type("Keyboard task");
-	await page.keyboard.press("Tab"); // -> Status (select)
-	await page.keyboard.press("Tab"); // -> Assignee
-	await page.keyboard.type("sam");
+	const form = page.getByRole("form", { name: "Add note" });
+	await form.getByLabel("Greeting").focus();
+	await page.keyboard.type("Keyboard hello");
 	await page.keyboard.press("Tab"); // -> submit
-	await expect(form.getByRole("button", { name: "Add task" })).toBeFocused();
+	await expect(form.getByRole("button", { name: "Say hello" })).toBeFocused();
 	await page.keyboard.press("Enter");
 	await expect(
-		page.getByRole("row").filter({ hasText: "Keyboard task" }),
+		page.getByRole("row").filter({ hasText: "Keyboard hello" }),
 	).toBeVisible();
 });

package/template/app/e2e/99-screens.spec.ts

@@ -0,0 +1,32 @@
+// Screen previews: a full-page screenshot of every manifest screen at
+// mobile (390x844) and desktop (1280x800) viewports, written to
+// screen-previews/ (gitignored) for the CI artifact and `make preview`.
+// No assertions beyond successful page load. Runs last (99-) so data
+// created by earlier specs makes the previews realistic.
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { expect, test } from "@playwright/test";
+import manifest from "../generated/manifest.json";
+
+const viewports = [
+	{ name: "mobile", width: 390, height: 844 },
+	{ name: "desktop", width: 1280, height: 800 },
+] as const;
+
+const outDir = join(__dirname, "..", "screen-previews");
+
+for (const screen of manifest.screens) {
+	for (const viewport of viewports) {
+		test(`preview: ${screen.key} (${viewport.name})`, async ({ page }) => {
+			await page.setViewportSize({ width: viewport.width, height: viewport.height });
+			await page.goto(screen.route, { waitUntil: "networkidle" });
+			await expect(page.getByRole("heading", { level: 1 }).first()).toBeVisible();
+			mkdirSync(outDir, { recursive: true });
+			await page.screenshot({
+				path: join(outDir, `${screen.key}-${viewport.name}.png`),
+				fullPage: true,
+			});
+		});
+	}
+}

package/template/app/package.json

@@ -10,9 +10,9 @@
 		"test:e2e": "next build && playwright test"
 	},
 	"dependencies": {
-		"@minlang/design-system": "^0.2.0",
-		"@minlang/runtime-web": "^0.2.0",
-		"@minlang/tailwind-preset": "^0.2.0",
+		"@minlang/design-system": "^0.2.1",
+		"@minlang/runtime-web": "^0.2.1",
+		"@minlang/tailwind-preset": "^0.2.1",
 		"next": "15.5.19",
 		"react": "19.2.7",
 		"react-dom": "19.2.7",

package/template/app/seed.ts

@@ -1,8 +1,8 @@
-// App wiring: bind the data adapter (in-memory default) with the
-// deterministic demo seed. Imported for its side effect by app/layout.tsx so
+// App wiring: bind the data adapter (in-memory default) with the welcome
+// app's starting content. Imported for its side effect by app/layout.tsx so
 // it runs once in the route-server bundle before any render or action.
-// WEB_DATA_ADAPTER=memory is the supported adapter for plan completion; a
-// real adapter (USE_REAL_SERVICES=true) would bind here instead.
+// The tables on the Files / Enhance / Resources screens are seeded here; the
+// notes list starts empty so the first thing you do is add one.
 
 import { createInMemoryAdapter } from "@minlang/runtime-web";
 import { bindServerAdapter } from "@minlang/runtime-web/server";
@@ -11,7 +11,24 @@ import { emptyAppState } from "./generated/state";
 bindServerAdapter(
 	createInMemoryAdapter({
 		...emptyAppState,
-		workspaces: [{ id: "w1", view: "board" }],
-		projects: [{ id: "p1", name: "General" }],
+		tours: [{ id: "t1", page: "welcome" }],
+		fileGuides: [
+			{ id: "f1", file: "*.ml", purpose: "The whole app: entities, rules, actions, screens, tests." },
+			{ id: "f2", file: "app/generated/", purpose: "Compiler output. Committed, never hand-edited." },
+			{ id: "f3", file: "app/", purpose: "Thin Next.js shell over the @minlang runtime." },
+			{ id: "f4", file: "minlang.json", purpose: "Pins the MinLang language + compiler versions." },
+			{ id: "f5", file: "AGENTS.md", purpose: "Instructions for AI coding agents working here." },
+		],
+		buildSteps: [
+			{ id: "s1", step: "Edit welcome.ml", detail: "Model your domain: entities, constraints, actions, screens." },
+			{ id: "s2", step: "make compile", detail: "Regenerate app/generated from the .ml source." },
+			{ id: "s3", step: "make test", detail: "Run the generated success / failure / no-change triads." },
+			{ id: "s4", step: "make dev", detail: "Open http://localhost:3111 and use your app." },
+		],
+		resources: [
+			{ id: "r1", topic: "Language rules", link: "github.com/codeshift-ai-solutions/minlang-releases/releases/latest/download/minlang-language-bundle.md" },
+			{ id: "r2", topic: "Run it", link: "make dev, then http://localhost:3111" },
+			{ id: "r3", topic: "Enhance it", link: "Edit welcome.ml, then make compile && make test" },
+		],
 	}),
 );

package/template/app/skins/README.md

@@ -0,0 +1,15 @@
+# Skins
+
+Custom renderers ("skins") for widget keys, registered in `../seed.ts` via
+`bindRegistryOverrides({ <widget>: Component })`. One skin per file
+(`<widget-key>.tsx`), presentation only: props are exactly `WidgetProps<K>`,
+copy comes only from the schema node, styling uses design-token classes
+(never hex/rgb literals), and state changes go through the provided
+server-action refs.
+
+The full recipe (including adapting Figma Make exports) is the **Skins**
+section of the language bundle:
+https://github.com/codeshift-ai-solutions/minlang-releases/releases/latest/download/minlang-language-bundle.md
+
+The contract is mechanically enforced — `make lint-skins`
+(`node scripts/lint-skins.mjs app/skins`) runs as part of `make test` and CI.

package/template/app/tests/welcome-flow.test.ts

@@ -0,0 +1,77 @@
+// BDD: the welcome demo's domain flows through dispatch + the in-memory
+// adapter — add a greeting, see the rejection path keep state unchanged,
+// navigate between screens, and replay a fixed trace deterministically.
+
+import { createInMemoryAdapter, dispatch } from "@minlang/runtime-web";
+import type { DataAdapter, DispatchDeps } from "@minlang/runtime-web";
+import { describe, expect, test } from "vitest";
+import { applyAddNote, applyShowFiles } from "../generated/actions";
+import type { AddNoteInput } from "../generated/actions";
+import { runNoteList } from "../generated/queries";
+import { emptyAppState } from "../generated/state";
+import type { AppState } from "../generated/state";
+
+const seed: AppState = {
+	...emptyAppState,
+	tours: [{ id: "t1", page: "welcome" }],
+};
+
+const fixedDeps = (adapter: DataAdapter<AppState>): DispatchDeps<AppState> => ({
+	adapter,
+	clock: { currentTime: () => "2026-01-01T00:00:00Z" },
+	rng: { draw: () => 7 },
+	identity: { currentActorId: () => "test-actor" },
+	logger: { info: () => undefined, warn: () => undefined, error: () => undefined },
+	correlationId: "c-test",
+	emptyState: emptyAppState,
+	newId: () => "id-fixed",
+});
+
+const noteInput = (overrides: Partial<AddNoteInput>): AddNoteInput => ({
+	id: "n1",
+	greeting: "Hello, MinLang",
+	actor_id: "test-actor",
+	...overrides,
+});
+
+describe("welcome demo flows", () => {
+	test("adding a greeting persists it to the notes list", async () => {
+		const adapter = createInMemoryAdapter<AppState>(seed);
+		const deps = fixedDeps(adapter);
+		expect((await dispatch(applyAddNote, noteInput({}), deps)).ok).toBe(true);
+		const state = (await adapter.load()) ?? emptyAppState;
+		expect(runNoteList(state, { tour: "t1" }).map((n) => n.greeting)).toEqual(["Hello, MinLang"]);
+	});
+
+	test("an empty greeting is rejected with the exact constraint message", async () => {
+		const adapter = createInMemoryAdapter<AppState>(seed);
+		const outcome = await dispatch(applyAddNote, noteInput({ greeting: "" }), fixedDeps(adapter));
+		expect(outcome.ok).toBe(false);
+		if (!outcome.ok) {
+			expect(outcome.error.message).toBe("a greeting is required");
+		}
+		expect(((await adapter.load()) ?? emptyAppState).notes).toHaveLength(0);
+	});
+
+	test("navigation switches the active page", async () => {
+		const adapter = createInMemoryAdapter<AppState>(seed);
+		const deps = fixedDeps(adapter);
+		expect((await dispatch(applyShowFiles, { tour: "t1", actor_id: "a" }, deps)).ok).toBe(true);
+		const state = (await adapter.load()) ?? emptyAppState;
+		expect(state.tours[0]?.page).toBe("files");
+	});
+
+	test("replay: a fixed trace yields a deep-equal final state across runs", async () => {
+		const run = async (): Promise<AppState> => {
+			const adapter = createInMemoryAdapter<AppState>(seed);
+			const deps = fixedDeps(adapter);
+			await dispatch(applyAddNote, noteInput({ id: "n1", greeting: "One" }), deps);
+			await dispatch(applyAddNote, noteInput({ id: "n2", greeting: "Two" }), deps);
+			await dispatch(applyShowFiles, { tour: "t1", actor_id: "test-actor" }, deps);
+			return (await adapter.load()) ?? emptyAppState;
+		};
+		const [first, second] = [await run(), await run()];
+		expect(first).toEqual(second);
+		expect(runNoteList(first, { tour: "t1" }).map((n) => n.greeting)).toEqual(["One", "Two"]);
+	});
+});

package/template/gitattributes

@@ -0,0 +1,4 @@
+**/generated/** linguist-generated=true
+**/generated/ui/wire/*.mlui linguist-generated=false linguist-detectable=false
+minlang-core/ linguist-vendored=true
+*.mlui text eol=lf

package/template/gitignore

@@ -3,6 +3,7 @@ node_modules/
 .vercel/
 playwright-report/
 test-results/
+screen-previews/
 coverage/
 *.tsbuildinfo
 .env

package/template/scripts/lint-skins.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// Mechanical SHELL_CONTRACT lint for registry skins (spec/target-web/SKIN_GUIDE.md).
+//
+// Usage: node scripts/lint-skins.mjs [dir...]   (default: app/skins, if it exists)
+//
+// Scans .ts/.tsx files line by line and exits 1 with file:line findings on:
+//   jsx-text        hardcoded copy as JSX text (.tsx only — heuristic below)
+//   color-literal   #hex (3/4/6/8) · rgb(/rgba(/hsl(/hsla( · Tailwind -[# classes
+//   forbidden-api   fetch( · Date.now · Math.random · new Date( · toLocale*
+//   adapter-import  imports of @minlang/runtime-web/server or any */adapters/* path
+//
+// jsx-text heuristic (documented contract): string literals are blanked, the
+// line is cut at any // comment, =>/<=/>= and space-surrounded </> comparison
+// operators are blanked, {…} JSX expressions are removed; the line is flagged when (a) letters remain between a `>` and a `<`
+// on the same line, or (b) the line is bare prose (letters/spaces/simple
+// punctuation, not a JS keyword) and the previous non-blank line ends with `>`
+// but not `=>`. Block comments are not masked. The shipped design system must
+// lint clean (regression-tested in scripts/tests/lint-skins.test.mjs).
+//
+// Opt-out, per offending line: trailing `// skin-lint-allow: <rule>[, <rule>...]`.
+// Exit codes: 0 clean · 1 findings · 2 usage error (explicit dir missing).
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const HEX_COLOR = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})\b/;
+const COLOR_FN = /\b(?:rgb|rgba|hsl|hsla)\s*\(/;
+const ARBITRARY_COLOR = /-\[#/;
+const FORBIDDEN_APIS = [
+	[/\bfetch\s*\(/, "fetch("],
+	[/\bDate\.now\b/, "Date.now"],
+	[/\bMath\.random\b/, "Math.random"],
+	[/\bnew\s+Date\s*\(/, "new Date("],
+	[/toLocale/, "toLocale* (locale-ambient formatting)"],
+];
+const SERVER_IMPORT = /@minlang\/runtime-web\/server/;
+const ADAPTER_PATH = /["'][^"']*\/adapters\/[^"']*["']/;
+const JS_KEYWORDS = new Set([
+	"return", "break", "continue", "else", "try", "finally", "default", "do",
+	"case", "new", "typeof", "void", "delete", "await", "yield", "async",
+	"export", "import", "const", "let", "var", "function", "class", "if",
+	"for", "while", "switch", "throw", "true", "false", "null", "undefined",
+]);
+const SKIP_DIRS = new Set(["node_modules", "dist", "generated", "coverage"]);
+
+/** Blank string-literal contents, preserving length and the quote chars. */
+const blankStrings = (line) =>
+	line.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`/g, (m) =>
+		m[0] + " ".repeat(m.length - 2) + m[0],
+	);
+
+/** Remove {…} JSX expressions and blank arrow/comparison operators. */
+const dropExpressions = (text) => {
+	let t = text.replace(/=>|<=|>=/g, "  ").replace(/ [<>] /g, "   ");
+	for (let prev = ""; prev !== t; ) {
+		prev = t;
+		t = t.replace(/\{[^{}]*\}/g, "");
+	}
+	return t;
+};
+
+const BARE_PROSE = /^[A-Za-z][A-Za-z0-9 ,.'!?-]*$/;
+
+/** Lint one file; returns findings [{line, rule, message}]. */
+const lintFile = (path) => {
+	const findings = [];
+	const isTsx = path.endsWith(".tsx");
+	let prevCode = "";
+	const lines = readFileSync(path, "utf8").split("\n");
+	lines.forEach((raw, index) => {
+		const blanked = blankStrings(raw);
+		const commentIdx = blanked.indexOf("//");
+		const allowed = new Set();
+		let code = raw;
+		let codeBlanked = blanked;
+		if (commentIdx !== -1) {
+			const match = raw.slice(commentIdx).match(/skin-lint-allow:\s*([a-z, -]+)/);
+			for (const rule of match === null ? [] : match[1].split(",")) {
+				allowed.add(rule.trim());
+			}
+			code = raw.slice(0, commentIdx);
+			codeBlanked = blanked.slice(0, commentIdx);
+		}
+		const report = (rule, message) => {
+			if (!allowed.has(rule)) {
+				findings.push({ line: index + 1, rule, message });
+			}
+		};
+		checkColors(code, report);
+		checkForbiddenApis(codeBlanked, report);
+		checkAdapterImports(code, report);
+		if (isTsx) {
+			checkJsxText(codeBlanked, prevCode, report);
+		}
+		if (code.trim() !== "") {
+			prevCode = code;
+		}
+	});
+	return findings;
+};
+
+const checkColors = (code, report) => {
+	if (HEX_COLOR.test(code)) {
+		report("color-literal", "hex color literal — style via design tokens / token classes");
+	}
+	if (COLOR_FN.test(code)) {
+		report("color-literal", "rgb()/hsl() color literal — style via design tokens");
+	}
+	if (ARBITRARY_COLOR.test(code)) {
+		report("color-literal", "Tailwind arbitrary color class — use token classes");
+	}
+};
+
+const checkForbiddenApis = (codeBlanked, report) => {
+	for (const [pattern, name] of FORBIDDEN_APIS) {
+		if (pattern.test(codeBlanked)) {
+			report("forbidden-api", `${name} is forbidden in skins (SHELL_CONTRACT nondeterminism/IO)`);
+		}
+	}
+};
+
+const checkAdapterImports = (code, report) => {
+	if (SERVER_IMPORT.test(code)) {
+		report("adapter-import", "@minlang/runtime-web/server import — skins never touch the adapter");
+	}
+	if (ADAPTER_PATH.test(code)) {
+		report("adapter-import", "adapter/store import — skins read only the schema node and deps");
+	}
+};
+
+const checkJsxText = (codeBlanked, prevCode, report) => {
+	const masked = dropExpressions(codeBlanked);
+	const between = masked.match(/>([^<>]*[A-Za-z][^<>]*)</);
+	if (between !== null) {
+		report("jsx-text", `hardcoded JSX text "${between[1].trim()}" — copy must come from the schema node`);
+		return;
+	}
+	const bare = masked.trim();
+	const prev = prevCode.trim();
+	if (
+		BARE_PROSE.test(bare) &&
+		!JS_KEYWORDS.has(bare) &&
+		prev.endsWith(">") &&
+		!prev.endsWith("=>")
+	) {
+		report("jsx-text", `hardcoded JSX text "${bare}" — copy must come from the schema node`);
+	}
+};
+
+const collectFiles = (dir, out) => {
+	for (const entry of readdirSync(dir).sort()) {
+		if (entry.startsWith(".") || SKIP_DIRS.has(entry)) {
+			continue;
+		}
+		const path = join(dir, entry);
+		if (statSync(path).isDirectory()) {
+			collectFiles(path, out);
+		} else if (/\.tsx?$/.test(entry)) {
+			out.push(path);
+		}
+	}
+	return out;
+};
+
+const main = () => {
+	const args = process.argv.slice(2);
+	let dirs = args;
+	if (args.length === 0) {
+		if (!existsSync("app/skins")) {
+			console.log("lint-skins: no app/skins directory — nothing to lint");
+			return 0;
+		}
+		dirs = ["app/skins"];
+	}
+	for (const dir of dirs) {
+		if (!existsSync(dir)) {
+			console.error(`lint-skins: no such directory: ${dir}`);
+			return 2;
+		}
+	}
+	const files = dirs.flatMap((dir) => collectFiles(dir, []));
+	let total = 0;
+	for (const file of files) {
+		for (const finding of lintFile(file)) {
+			total += 1;
+			console.error(`${file}:${finding.line}: [${finding.rule}] ${finding.message}`);
+		}
+	}
+	if (total > 0) {
+		console.error(`lint-skins: ${total} finding(s) in ${files.length} file(s)`);
+		return 1;
+	}
+	console.log(`lint-skins: ${files.length} file(s) clean`);
+	return 0;
+};
+
+process.exit(main());

package/template/app/e2e/01-board.spec.ts

@@ -1,68 +0,0 @@
-// Core journeys: create a task, see the rejection path, move and rename it.
-// Deterministic: every run starts a fresh server with the same seed.
-
-import { expect, test } from "@playwright/test";
-
-test.describe.configure({ mode: "serial" });
-
-test("create task journey: form -> table row", async ({ page }) => {
-	await page.goto("/");
-	await expect(page.getByRole("heading", { name: "Task board" })).toBeVisible();
-	await expect(page.getByRole("note")).toContainText("No task yet");
-
-	const form = page.getByRole("form", { name: "Create task" });
-	await form.getByLabel("Title").fill("Ship the web target");
-	await form.getByLabel("Status").selectOption("todo");
-	await form.getByLabel("Assignee").fill("casey");
-	await form.getByRole("button", { name: "Add task" }).click();
-
-	const table = page.getByRole("table", { name: "Task board" });
-	await expect(table).toBeVisible();
-	await expect(table.getByRole("row").filter({ hasText: "Ship the web target" })).toBeVisible();
-});
-
-test("validation rejection shows the exact constraint message", async ({ page }) => {
-	await page.goto("/");
-	const form = page.getByRole("form", { name: "Create task" });
-	await form.getByLabel("Status").selectOption("doing");
-	await form.getByLabel("Title").fill("Doing without assignee");
-	await form.getByRole("button", { name: "Add task" }).click();
-	await expect(form.getByRole("alert")).toHaveText("assignee is required when a task is doing");
-});
-
-test("move task journey: status changes in the table", async ({ page }) => {
-	await page.goto("/");
-	const create = page.getByRole("form", { name: "Create task" });
-	await create.getByLabel("Title").fill("Move me");
-	await create.getByLabel("Assignee").fill("alex");
-	await create.getByRole("button", { name: "Add task" }).click();
-	await expect(page.getByRole("table", { name: "Task board" })).toBeVisible();
-
-	const move = page.getByRole("form", { name: "Move task" });
-	await move.getByLabel("Id").selectOption({ label: "Move me" });
-	await move.getByLabel("Status").selectOption("doing");
-	await move.getByRole("button", { name: "Move task" }).click();
-	const row = page.getByRole("row").filter({ hasText: "Move me" });
-	await expect(row).toContainText("doing");
-});
-
-test("rename task journey + projects navigation", async ({ page }) => {
-	await page.goto("/");
-	const create = page.getByRole("form", { name: "Create task" });
-	await create.getByLabel("Title").fill("Old title");
-	await create.getByRole("button", { name: "Add task" }).click();
-	await expect(page.getByRole("table", { name: "Task board" })).toBeVisible();
-
-	const rename = page.getByRole("form", { name: "Rename task" });
-	await rename.getByLabel("Id").selectOption({ label: "Old title" });
-	await rename.getByLabel("Title").fill("New title");
-	await rename.getByRole("button", { name: "Rename task" }).click();
-	await expect(page.getByRole("row").filter({ hasText: "New title" })).toBeVisible();
-
-	await page.goto("/screens/projects");
-	await expect(page.getByRole("heading", { name: "Projects" })).toBeVisible();
-	const project = page.getByRole("form", { name: "Create project" });
-	await project.getByLabel("Name").fill("Platform");
-	await project.getByRole("button", { name: "Add project" }).click();
-	await expect(page.getByRole("row").filter({ hasText: "Platform" })).toBeVisible();
-});

package/template/app/tests/task-flow.test.ts

@@ -1,111 +0,0 @@
-// BDD: end-to-end domain flows through dispatch + the in-memory adapter —
-// create → move → rename journeys, rejection leaves state unchanged, and a
-// deterministic replay over a fixed input trace.
-
-import { createInMemoryAdapter, dispatch } from "@minlang/runtime-web";
-import type { DataAdapter, DispatchDeps } from "@minlang/runtime-web";
-import { describe, expect, test } from "vitest";
-import { applyCreateTask, applyMoveTask, applyRenameTask } from "../generated/actions";
-import type { CreateTaskInput } from "../generated/actions";
-import { runTaskBoard } from "../generated/queries";
-import { emptyAppState } from "../generated/state";
-import type { AppState } from "../generated/state";
-
-const seed: AppState = {
-	...emptyAppState,
-	workspaces: [{ id: "w1", view: "board" }],
-	projects: [{ id: "p1", name: "General" }],
-};
-
-const fixedDeps = (adapter: DataAdapter<AppState>): DispatchDeps<AppState> => ({
-	adapter,
-	clock: { currentTime: () => "2026-01-01T00:00:00Z" },
-	rng: { draw: () => 7 },
-	identity: { currentActorId: () => "test-actor" },
-	logger: { info: () => undefined, warn: () => undefined, error: () => undefined },
-	correlationId: "c-test",
-	emptyState: emptyAppState,
-	newId: () => "id-fixed",
-});
-
-const taskInput = (overrides: Partial<CreateTaskInput>): CreateTaskInput => ({
-	id: "t1",
-	project: "p1",
-	title: "Ship the web target",
-	status: "todo",
-	assignee: "",
-	created_at: "2026-01-01T00:00:00Z",
-	actor_id: "test-actor",
-	...overrides,
-});
-
-describe("task-tracker domain flows", () => {
-	test("create → move → rename journey persists each step", async () => {
-		const adapter = createInMemoryAdapter<AppState>(seed);
-		const deps = fixedDeps(adapter);
-		expect((await dispatch(applyCreateTask, taskInput({}), deps)).ok).toBe(true);
-		expect(
-			(await dispatch(applyMoveTask, { id: "t1", status: "doing", actor_id: "a" }, deps)).ok,
-		).toBe(false); // assignee required when doing
-		expect(
-			(
-				await dispatch(
-					applyRenameTask,
-					{ id: "t1", title: "Ship it", actor_id: "a" },
-					deps,
-				)
-			).ok,
-		).toBe(true);
-		const state = (await adapter.load()) ?? emptyAppState;
-		expect(runTaskBoard(state, { workspace: "w1" }).map((t) => t.title)).toEqual(["Ship it"]);
-	});
-
-	test("rejection returns the exact constraint message and persists nothing", async () => {
-		const adapter = createInMemoryAdapter<AppState>(seed);
-		const outcome = await dispatch(
-			applyCreateTask,
-			taskInput({ title: "" }),
-			fixedDeps(adapter),
-		);
-		expect(outcome.ok).toBe(false);
-		if (!outcome.ok) {
-			expect(outcome.error.message).toBe("title is required");
-		}
-		expect(((await adapter.load()) ?? emptyAppState).tasks).toHaveLength(0);
-	});
-
-	test("unknown project is rejected by the count join", async () => {
-		const adapter = createInMemoryAdapter<AppState>(seed);
-		const outcome = await dispatch(
-			applyCreateTask,
-			taskInput({ project: "ghost" }),
-			fixedDeps(adapter),
-		);
-		expect(outcome.ok).toBe(false);
-		if (!outcome.ok) {
-			expect(outcome.error.message).toBe("project does not exist");
-		}
-	});
-
-	test("replay: a fixed trace yields a deep-equal final state across runs", async () => {
-		const run = async (): Promise<AppState> => {
-			const adapter = createInMemoryAdapter<AppState>(seed);
-			const deps = fixedDeps(adapter);
-			await dispatch(applyCreateTask, taskInput({ id: "t1", title: "One" }), deps);
-			await dispatch(applyCreateTask, taskInput({ id: "t2", title: "Two" }), deps);
-			await dispatch(
-				applyMoveTask,
-				{ id: "t2", status: "done", actor_id: "test-actor" },
-				deps,
-			);
-			await dispatch(applyRenameTask, { id: "t1", title: "Won", actor_id: "test-actor" }, deps);
-			return (await adapter.load()) ?? emptyAppState;
-		};
-		const [first, second] = [await run(), await run()];
-		expect(first).toEqual(second);
-		expect(runTaskBoard(first, { workspace: "w1" }).map((t) => [t.title, t.status])).toEqual([
-			["Won", "todo"],
-			["Two", "done"],
-		]);
-	});
-});