create-minlang-app 0.3.0 → 0.4.1

package/bin.mjs

@@ -65,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.3.0",
+  "version": "0.4.1",
   "description": "Scaffold a MinLang web app: write one .ml file, compile with ml1, deploy.",
   "license": "MIT",
   "repository": {

package/template/AGENTS.md

@@ -12,6 +12,17 @@ To change behavior, edit `__APP_NAME__.ml`, then run `make compile`.
 Never edit files under `app/generated/` — CI recompiles with `--check`
 and fails the build if they drift from the `.ml` source.
 
+For UI changes, sketch the intended screens in `ui/design/screens.mlui` first.
+Then translate that sketch into `screen` blocks in `__APP_NAME__.ml`, compile,
+and compare the generated `app/generated/ui/wire/*.mlui` projections. The
+`ui/design` sketch is hand-authored; generated wireframes are not.
+
+When product behavior cannot yet fit the language (remote services, uploads,
+rich local UI, AI structured outputs, full app shell/test generation), read
+`MINLANG_LANGUAGE_SUPPORT.md`. `make compile` refreshes
+`app/generated/MINLANG_LANGUAGE_SUPPORT.md`; agents should write any audit
+results to `MINLANG_LANGUAGE_SUPPORT_RESULTS.md`, not into generated output.
+
 ## Language authority (fetch before writing MinLang)
 
 Download the single-file language bundle and read it before producing or
@@ -27,6 +38,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 |
@@ -34,11 +56,12 @@ detector list, and the end-to-end web-app authoring guide. Highlights:
 | One-time setup | `corepack enable && corepack prepare pnpm@10.33.0 --activate` |
 | Validate the program | `make validate` |
 | Compile to `app/generated/` | `make compile` |
+| Refresh language-support prompt without compiling | `ml1 support __APP_NAME__.ml` |
 | 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 + deps | `make update` |
+| 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` |

package/template/MINLANG_LANGUAGE_SUPPORT.md

@@ -0,0 +1,74 @@
+# MinLang language support brief for `__APP_NAME__`
+
+This file is for coding agents and maintainers. It is not app code, and it is
+not proof that the capabilities below exist in the current language. It explains
+what MinLang must gain before this project can delete custom web shell, API,
+upload, provider, and test wiring.
+
+## Current status
+
+- Current web support covers persisted entities, constraints, pure actions,
+  queries, declarative screens, static themes/assets, generated reducers,
+  server action boundaries, screen schemas, wireframes, and generated unit tests
+  from MinLang test triads.
+- Remote provider calls, uploads, local client state, rich forms, structured AI
+  outputs, and full app-shell/test generation need a future bundle and compiler
+  work before app authors can rely on them.
+
+## Roadmap checklist
+
+### Declarative secrets, config, and services
+
+MinLang needs first-class declarations for provider secrets, environment-backed
+config, base URLs, auth headers, endpoint schemas, generated `.env.example`,
+and safe missing-secret errors.
+
+### Server-only remote effects and action pipelines
+
+Provider calls, retries, downloads, fallback chains, and persistence-after-effect
+need an explicit server-only boundary before they can be generated safely.
+
+### File inputs, uploads, and generated image assets
+
+Browser file inputs, multipart transport, server-side blobs, previews, MIME
+allowlists, size limits, URL fields, hex colors, and image transparency metadata
+need typed language support.
+
+### AI prompt templates and structured outputs
+
+Prompt construction, vision inputs, provider model selection, JSON schemas,
+normalization, fallback chains, and traceable prompt persistence need language
+and validator ownership.
+
+### Rich screens, local state, forms, and events
+
+Full product UI needs local screen state, form controls, event handlers,
+conditional result panels, root-route bindings, and richer accessibility
+metadata.
+
+### Structured theme, layout, and component variants
+
+Product-grade web styling needs validated stack/grid/card/panel/result-grid
+primitives and tokenized variants for buttons, tabs, fields, previews, alerts,
+and swatches.
+
+### Complete app shell and generated test suites
+
+The web target should eventually generate package/config/env examples, seed
+adapter binding, unit and pipeline tests, UI flows, accessibility, keyboard,
+performance, and E2E checks from MinLang declarations.
+
+## Agent prompt
+
+Read this file together with the current MinLang bundle and the app source.
+Then write findings to `MINLANG_LANGUAGE_SUPPORT_RESULTS.md` with:
+
+1. The product behavior still implemented outside MinLang.
+2. The language/runtime/codegen feature that would absorb each behavior.
+3. The validation rule or detector needed to keep it deterministic and safe.
+4. The generated files that should disappear once the feature exists.
+5. The tests required before deleting handwritten code.
+
+Do not edit a published language bundle in place. New syntax or enforcement
+rules require a new full versioned bundle, a migration ledger entry, parser and
+validator support, codegen support, docs, and deterministic tests.

package/template/README.md

@@ -3,6 +3,12 @@
 A MinLang web app. The whole application lives in `__APP_NAME__.ml`;
 `app/generated/` is compiler output (committed, never edited); `app/` holds
 the thin Next.js shell consuming the published `@minlang/*` runtime.
+Sketch screen changes first in `ui/design/screens.mlui`, then encode them in
+the `.ml` `screen` blocks and compare against `app/generated/ui/wire/*.mlui`
+after compile.
+Read `MINLANG_LANGUAGE_SUPPORT.md` when the app needs behavior the current
+bundle cannot express yet; generated compiles also refresh a copy under
+`app/generated/`.
 
 ```bash
 corepack enable && corepack prepare pnpm@10.33.0 --activate

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/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/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/ui/design/screens.mlui

@@ -0,0 +1,74 @@
+Source ASCII UI design for examples/welcome/welcome.ml.
+Author this first, then encode it as MinLang `screen` blocks and compare with
+web/generated/ui/wire/*.mlui after `make compile-web EXAMPLE=welcome`.
+
+── Welcome ───────────────────────────────────────────────────────────────────
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Welcome to MinLang                                                           │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ The whole app is one .ml file. Edit it, run make compile, and this UI        │
+│ updates.                                                                     │
+│                                                                              │
+│ Try the demo: add a note below, then take the tour.                          │
+│                                                                              │
+│ Notes                                                                        │
+│ ┌──────────────────────────────────────────────────────────────────────────┐ │
+│ │ Greeting                                                                 │ │
+│ ├──────────────────────────────────────────────────────────────────────────┤ │
+│ │ Hi from MinLang                                                          │ │
+│ └──────────────────────────────────────────────────────────────────────────┘ │
+│                                                                              │
+│ [ Say hello ]                                                                │
+│ [ What's in this project ]   [ Learn more ]                                  │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+── Files ─────────────────────────────────────────────────────────────────────
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ What's in this project                                                       │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ Everything is generated from your .ml source. Edit it, never app/generated.  │
+│                                                                              │
+│ ┌───────────────────────┬──────────────────────────────────────────────────┐ │
+│ │ File                  │ Purpose                                          │ │
+│ ├───────────────────────┼──────────────────────────────────────────────────┤ │
+│ │ *.ml                  │ Entities, constraints, actions, screens, tests   │ │
+│ │ app/generated/        │ Compiler output; never hand-edited              │ │
+│ │ AGENTS.md             │ Instructions for AI coding agents                │ │
+│ └───────────────────────┴──────────────────────────────────────────────────┘ │
+│                                                                              │
+│ [ How to enhance it ]   [ Back to start ]                                    │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+── Enhance ───────────────────────────────────────────────────────────────────
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Make it yours                                                                │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ Describe your own domain in the .ml, then compile and test.                  │
+│                                                                              │
+│ ┌────────────────────┬─────────────────────────────────────────────────────┐ │
+│ │ Step               │ Detail                                              │ │
+│ ├────────────────────┼─────────────────────────────────────────────────────┤ │
+│ │ Edit *.ml          │ Model entities, constraints, actions, screens       │ │
+│ │ make compile       │ Regenerate app/generated                            │ │
+│ │ make test          │ Run generated triads and integration tests          │ │
+│ └────────────────────┴─────────────────────────────────────────────────────┘ │
+│                                                                              │
+│ [ Resources ]   [ Back to start ]                                            │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+── Resources ─────────────────────────────────────────────────────────────────
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Learn more                                                                   │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ The language bundle has the full rules and the web authoring guide.          │
+│                                                                              │
+│ ┌────────────────────┬─────────────────────────────────────────────────────┐ │
+│ │ Topic              │ Link                                                │ │
+│ ├────────────────────┼─────────────────────────────────────────────────────┤ │
+│ │ Language rules     │ releases/latest/download/minlang-language-bundle.md │ │
+│ │ Run it             │ make dev                                            │ │
+│ │ Enhance it         │ edit *.ml, then make compile && make test           │ │
+│ └────────────────────┴─────────────────────────────────────────────────────┘ │
+│                                                                              │
+│ [ Back to start ]   [ What's in this project ]                               │
+└──────────────────────────────────────────────────────────────────────────────┘

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"],
-		]);
-	});
-});