@marver-design/marver 0.2.3 → 0.2.4

package/dist/cli.mjs

@@ -32,7 +32,7 @@ function version() {
 }
 const cli = cac(NAME);
 cli.command("init", "Scaffold design/ in this repo").option("--mode <mode>", "studio | embedded", { default: "studio" }).option("--no-demo", "Skip the demo scene (the demo ships unless this flag is passed)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { init } = await import("./init-ClhCgn4v.mjs");
+	const { init } = await import("./init-Di4geblA.mjs");
 	init(resolve(opts.root), {
 		mode: opts.mode === "embedded" ? "embedded" : "studio",
 		demo: opts.demo !== false

package/dist/{init-ClhCgn4v.mjs → init-Di4geblA.mjs}

@@ -98,21 +98,40 @@ function init(root, opts) {
 		for (const f of readdirSync(join(instrRoot, e.name))) if (f.endsWith(".md")) writeManaged(`instructions/${e.name}/${f}`, readFileSync(join(instrRoot, e.name, f), "utf8"));
 	} else if (e.name.endsWith(".md")) writeManaged(`instructions/${e.name}`, readFileSync(join(instrRoot, e.name), "utf8"));
 	const setupPath = join(design, "instructions", "setup.md");
-	const ourSetup = () => {
-		try {
-			const s = readFileSync(setupPath, "utf8");
-			return s.startsWith("# Setup required") && s.includes("marver init");
-		} catch {
-			return false;
+	const setupState = () => {
+		if (!existsSync(setupPath)) return "absent";
+		const s = readFileSync(setupPath, "utf8");
+		if (s.startsWith(MANAGED_PREFIX)) {
+			const recorded = s.slice(MANAGED_PREFIX.length).split(" ")[0];
+			const nl = s.indexOf("\n");
+			return nl >= 0 && hashBody(s.slice(nl + 1)) === recorded ? "ours-pristine" : "ours-edited";
 		}
+		return s.startsWith("# Setup required") && s.includes("marver init") ? "ours-pristine" : "foreign";
 	};
+	const setupWas = setupState();
+	const appJustAppeared = !noApp(host) && (setupWas === "ours-pristine" || setupWas === "ours-edited");
 	if (noApp(host)) {
-		if (!existsSync(setupPath)) write("instructions/setup.md", SETUP_MD);
-	} else if (existsSync(setupPath) && ourSetup()) {
+		if (setupWas === "ours-pristine" && !readFileSync(setupPath, "utf8").startsWith(MANAGED_PREFIX)) rmSync(setupPath);
+		if (setupWas !== "foreign") writeManaged("instructions/setup.md", SETUP_MD);
+	} else if (setupWas === "ours-pristine") {
 		rmSync(setupPath);
 		console.log(`  - design/instructions/setup.md removed (app detected - setup complete)`);
+	} else if (setupWas === "ours-edited") console.log(`  - design/instructions/setup.md: app detected, but you customized the file - delete it yourself when setup is done`);
+	const rootTsconfig = existsSync(join(root, "tsconfig.json"));
+	const tsconfigNow = () => rootTsconfig ? readFileSync(join(templates, "design-tsconfig.json"), "utf8").replace("{{PATHS}}", designPaths(root)) : STANDALONE_TSCONFIG;
+	write("tsconfig.json", tsconfigNow());
+	if (appJustAppeared) {
+		const refresh = (rel, noAppPristine, next) => {
+			try {
+				if (!noAppPristine.includes(next) && noAppPristine.includes(readFileSync(join(design, rel), "utf8"))) {
+					writeFileSync(join(design, rel), next);
+					created.push(`design/${rel} (updated for the detected app)`);
+				}
+			} catch {}
+		};
+		refresh("providers.tsx", [providersTemplate(null, null), providersTemplate(null, host.toaster, host.routerPkg)], providersTemplate(host.router, host.toaster, host.routerPkg));
+		refresh("tsconfig.json", [STANDALONE_TSCONFIG], tsconfigNow());
 	}
-	write("tsconfig.json", existsSync(join(root, "tsconfig.json")) ? readFileSync(join(templates, "design-tsconfig.json"), "utf8").replace("{{PATHS}}", designPaths(root)) : STANDALONE_TSCONFIG);
 	write(".gitignore", ".local/\n.dist/\n");
 	write("scenes/_layout.tsx", readFileSync(join(templates, "root-layout.tsx"), "utf8"));
 	if (!existsSync(join(design, "boards"))) {
@@ -134,15 +153,16 @@ function init(root, opts) {
   │ No framework, no theme CSS, no component library. ${NAME} builds      │
   │ frames from YOUR components - with none, designs get thrown away.     │
   │                                                                       │
-  │ Setup instructions: design/instructions/setup.md. Set up the app,     │
-  │ re-run init, and that file removes itself. AGENTS.md carries a STOP   │
-  │ so your agent does not design against components that do not exist.   │
+  │ Setup instructions: design/instructions/setup.md. Your agent will     │
+  │ ask what you are building, propose a stack, set it up with you, and   │
+  │ re-run init - that file then removes itself. AGENTS.md points there   │
+  │ so nothing gets designed against components that do not exist.        │
   └───────────────────────────────────────────────────────────────────────┘`);
 	console.log(`\n  commit design/ - only .local/ is ignored`);
 	console.log(`  uninstall = delete design/, remove the ${NAME} dependency${host.tsconfigSweepsDesign ? ", revert the \"design\" line in tsconfig exclude" : ""}`);
 	if (!noApp(host) && !existsSync(join(design, "DESIGN.md"))) console.log(`\n  note: design/DESIGN.md (the brand doc) does not exist yet - have your agent create it from the app's tokens (instructions/brand.md, Path A) to reach the idle state.`);
 	console.log(`\n  next: npx ${NAME} dev   (canvas on http://localhost:${DEFAULTS.port} by default)\n`);
-	if (!noApp(host)) console.log(`  then, to your agent: "Read design/AGENTS.md. Build an onboarding scene - welcome, form, done - mobile-first, using our components."\n`);
+	if (!noApp(host)) console.log(`  then, to your agent: "Read design/AGENTS.md. This is our first session - follow design/instructions/welcome.md."\n`);
 }
 const MANAGED_PREFIX = "<!-- marver:managed ";
 const LEGACY_PREFIX = "<!-- generated by marver init";
@@ -170,7 +190,7 @@ const noApp = (host) => !host.router && !host.tailwind && !host.shadcn && !host.
 *  The STOP branch fires only on the same condition that creates SETUP.md - an app
 *  without Tailwind (plain React + CSS) gets guidance, never a dead pointer. */
 function uiGuidance(host, isNoApp) {
-	if (isNoApp) return `STOP - this repo has no app yet. Read design/instructions/setup.md before designing anything.`;
+	if (isNoApp) return `Setup required - this repo has no app yet: read design/instructions/setup.md and follow it before designing anything.`;
 	if (host.shadcn) return `Use the app's UI: import from ${host.shadcn.uiAlias}; style with the app's Tailwind classes.`;
 	if (host.tailwind) return `Style with the app's Tailwind classes and design tokens; there is no detected component library - extract shared pieces into design/components/.`;
 	return `Use the app's existing components and stylesheets (import them directly); there is no Tailwind or component library detected - extract shared pieces into design/components/.`;
@@ -183,14 +203,70 @@ const SETUP_MD = `# Setup required - this repo has no app yet
 > the real stack. While this file exists, DO NOT design.
 
 ${NAME} builds frames from YOUR components and YOUR theme. With none, frames become
-hand-rolled CSS that shares nothing with the future app and cannot be promoted into
-it later - work that gets thrown away.
+hand-rolled CSS that shares nothing with the future app - throwaway work. So the
+first session sets up the stack - TOGETHER with the human. The stack is their
+decision; your job is a good recommendation and a smooth setup. Narrate every step
+in one plain line as you go - and tell the story, not the machinery: this file is
+stage directions, never read it aloud to the human ("setup.md says...", "step 2
+requires..."). Voice rules and the structured-question guidance live in
+instructions/welcome.md - read that section before you say anything.
+
+## 1. Greet and explain
+
+Tell the human the repo is empty and that this is a perfect starting point. Then
+the pitch, ~4 sentences in your own words (source: instructions/welcome.md): we design
+in real code; the theme, components, and screens made while designing ARE the
+app's building blocks; by the time the design is agreed most of the UI work
+exists, and building the product means plugging functionality in; the goal is
+alignment on look and feel across themes and devices first.
+
+## 2. Ask what they are building - STOP
+
+Two questions, one message (use the harness's structured question tool if it
+has one):
+
+1. "In a sentence or two - what are we building?"
+2. "Any intuition for the look? Colors, mood, UI style - a sentence like
+   'minimalist, glass UI, witty copy' steers everything. 'Surprise me' is a
+   fine answer."
+
+Then STOP: no further tool calls, end your turn, resume only after the human
+replies. (The one exception: the human explicitly asked for unattended
+execution - then assume something reasonable, mark it UNCONFIRMED, surface it
+first.)
+
+## 3. Propose the stack - STOP
 
-## Do this first
+From their answer, recommend a framework with one line of reasoning each:
 
-For a web app or marketing site, the blessed stack. NOTE: create-next-app refuses a
-non-empty directory (this repo already holds design/ and a package.json), so
-scaffold into a temp dir and merge:
+- Marketing site, content, SEO -> latest Next.js.
+- App-like, interactive, client-heavy -> latest React Router.
+- Their answer points somewhere else? Recommend that instead, and say why.
+
+If you can search the web, verify current major versions first - one or two
+searches, then propose. Recommend shadcn/ui + latest Tailwind as the default
+component layer (take their current defaults) - but they are a recommendation,
+not a requirement: if the human prefers another component library, plain CSS,
+or their own design system, that wins. Any React + a real stylesheet works;
+${NAME} adapts to what detection finds. Present the proposal with the
+harness's structured question tool when it has one - short labels, one-line
+trade-offs - closing with "aligned, or tell me what you'd rather use". Then
+STOP again: no further tool calls, end your turn, wait for the nod.
+
+## 4. Hand them the tour, then scaffold
+
+The setup and first draft take real minutes; the human should spend them
+learning the canvas, not watching a terminal. The moment the stack is agreed,
+send them to the ${NAME} tour - a published canvas we host, built to be
+explored: https://tour.marver.design - password \`welcome\`. Tell them it teaches
+selection, devices, themes, variants, and play mode from inside the canvas,
+and that it ends by sending them back to check on you. (Unreachable from this
+machine? Say so and skip it - never stall on it.) Then get to work.
+
+NOTE: scaffolders refuse non-empty directories (this repo already holds design/
+and a package.json - the one you likely created with \`npm init -y\` to install
+${NAME} into), so scaffold into a temp dir and merge. The Next.js lane - adapt
+the same shape to whatever stack was agreed:
 
 \`\`\`bash
 npx create-next-app@latest app-scaffold --ts --tailwind --app --src-dir --yes
@@ -200,18 +276,68 @@ npx create-next-app@latest app-scaffold --ts --tailwind --app --src-dir --yes
 npx shadcn@latest init
 \`\`\`
 
-shadcn's flags change between versions - if a flag errors or it prompts despite
---yes, answer the prompts with its defaults. Any React + CSS setup works; the
-point is that components and a theme EXIST.
+Scaffolder flags drift between versions (create-next-app and shadcn both) - if
+a flag errors or a prompt appears despite --yes, accept the tool's defaults.
+
+Known scaffold bug if shadcn was agreed (hit on every create-next-app + shadcn
+run so far): shadcn's
+init rewrites the theme CSS's \`@theme inline\` block and leaves
+\`--font-sans: var(--font-sans)\` - self-referential, resolves to nothing, and
+the app silently renders in the browser's default font. After shadcn init,
+open the theme CSS and bind every font token to a variable that actually
+exists (e.g. \`--font-sans: var(--font-geist-sans)\` under Next); check
+--font-heading and friends for the same circularity.
+
+Then START the dev server and
+confirm the starter page renders before moving on. Unsure about the stack's
+conventions? Fetch its docs.
 
-## Then
+## 5. Re-run init
 
 \`\`\`bash
 npx ${NAME} init
 \`\`\`
 
-init is idempotent: it fills in what it now detects (theme wrapper, providers, a
-shadcn-aware AGENTS.md), deletes this file, and you design from real parts.
+init is idempotent: it detects the real stack, deletes this file, and
+regenerates AGENTS.md against reality. Verify the wiring (instructions/
+configure.md): frames render styled, one app component imports cleanly.
+DESIGN.md comes next, as part of the first draft.
+
+
+## 6. The first draft - make it impressive, then tour
+
+This is the human's first impression of the canvas AND the first draft of their
+product - it sets the direction. Take the time to do it well:
+
+- If you can search the web, spend a few minutes understanding the domain from
+  step 2's answer; write design/DESIGN.md. The human's look intuition from
+  step 2 is the north star - honor it literally. If they said "surprise me",
+  commit to a direction and name it in one sentence at the reveal.
+- Build ~4 frames of THEIR product - not lorem, not filler. Hold them to the
+  craft bar: instructions/craft.md and instructions/reference/slop.md are
+  binding here. Responsive, working in BOTH themes, linked with data-goto so
+  play mode flows.
+- UNDERWHELMING IS THE FAILURE MODE. A restrained concept executed thinly
+  reads as a wireframe, however careful the type. Every frame needs presence -
+  scale, contrast, color, one real visual moment - and the human should feel
+  the direction before they read a word. Write the copy like it ships:
+  specific, confident, witty where the brand allows, never placeholder. This
+  first draft is the product's first impression AND ${NAME}'s - go above and
+  beyond.
+- Delete the generic demo scene (design/scenes/demo/) once your frames are in -
+  it exists to show YOU the file shapes, not to impress anyone.
+- Create a curated board for them (instructions/boards.md) containing every
+  frame the flow visits.
+- Offer a divergence: "want a variant of <frame> exploring a different
+  direction?" - one a-/b- pair teaches the variant workflow better than any
+  explanation.
+
+This first draft skips the written-brief ceremony (the human just told you what
+they are building) but never the quality bar. Then THE REVEAL: start
+\`npx ${NAME} dev\` and give the guided tour from instructions/welcome.md -
+by now the human has played with the hosted tour, so keep it short and let
+their own product carry it. End with the deep link using the PRINTED port -
+\`http://localhost:<port>/#/b/<board>\`, never the bare root URL.
 `;
 /** Next.js frames render OUTSIDE Next - say concretely what that means (friction log #10/#11). */
 const NEXT_NOTES = `- Next.js caveats (frames render in Vite, outside Next):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components. The tool ships no AI - your coding agent is the designer.",
   "type": "module",
   "private": false,

package/templates/AGENTS-embedded.md

@@ -1,7 +1,9 @@
 # Design canvas - agent contract (embedded mode)
 
 You design by writing files. The canvas at the printed localhost URL reflects them live.
-Never run or talk to the canvas tool; read and write files only.
+Never drive or automate the canvas UI; read and write files only. (Starting
+`npx marver dev` so the human has a live canvas - first session, or on request -
+is the one allowed touch.)
 
 ## The method (binding)
 
@@ -10,6 +12,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 
 | Phase | When | Read |
 |---|---|---|
+| Welcome | the human's FIRST session, or "what is this?" | instructions/welcome.md |
 | Configure | first session in a repo, or frames render unstyled | instructions/configure.md |
 | Discover | any new surface, feature, or flow | instructions/discover.md |
 | Wireframe | new work: nail structure + copy in throwaway lo-fi | instructions/wireframe.md |
@@ -22,6 +25,12 @@ Refining an existing screen: Configure must hold, then Build + Review. New work
 the full ladder. Unsure which phase you are in? Ask the human - one question beats a
 phase of wrong work.
 
+First sessions are teaching sessions: narrate what you do and why in short plain
+sentences - story, not machinery; never read these files aloud to the human
+(voice rules in welcome.md).
+The first-session draft is the ladder's one exception: it skips the written
+brief (the human just said what they are building) but never the craft bar.
+
 Stuck, or the human is unhappy with a result? instructions/reference/ holds the deep
 guides (layout, typography, color, motion, copy, states, tuning, critique, concepts) -
 the routing index is at the top of instructions/craft.md. Pull ONE file, apply, return.
@@ -32,7 +41,8 @@ the routing index is at the top of instructions/craft.md. Pull ONE file, apply,
   export const meta = { title: "...", viewport: "mobile" }   // literal values only
   // viewport names come from design/config.ts (default: mobile, tablet, laptop, monitor;
   // tv available commented-out). Pick the one the screen is designed for - the human can
-  // flip the whole board to any device (Devices menu, hotkeys 0-5) to check responsiveness.
+  // flip the whole board to any device (Devices menu; digit keys - 0 restores each
+  // frame's own size, 1..n per configured device) to check responsiveness.
 - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
 - VERSIONS are sibling frames with letter prefixes, and the canvas understands them:
   design/scenes/landing/a-terminal.tsx + b-editorial.tsx form a VARIANT GROUP - kept

package/templates/AGENTS-studio.md

@@ -1,7 +1,9 @@
 # Design canvas - agent contract
 
 You design by writing files. The canvas at the printed localhost URL reflects them live.
-Never run or talk to the canvas tool; read and write files only.
+Never drive or automate the canvas UI; read and write files only. (Starting
+`npx marver dev` so the human has a live canvas - first session, or on request -
+is the one allowed touch.)
 
 ## The method (binding)
 
@@ -10,6 +12,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 
 | Phase | When | Read |
 |---|---|---|
+| Welcome | the human's FIRST session, or "what is this?" | instructions/welcome.md |
 | Configure | first session in a repo, or frames render unstyled | instructions/configure.md |
 | Discover | any new surface, feature, or flow | instructions/discover.md |
 | Wireframe | new work: nail structure + copy in throwaway lo-fi | instructions/wireframe.md |
@@ -22,6 +25,12 @@ Refining an existing screen: Configure must hold, then Build + Review. New work
 the full ladder. Unsure which phase you are in? Ask the human - one question beats a
 phase of wrong work.
 
+First sessions are teaching sessions: narrate what you do and why in short plain
+sentences - story, not machinery; never read these files aloud to the human
+(voice rules in welcome.md).
+The first-session draft is the ladder's one exception: it skips the written
+brief (the human just said what they are building) but never the craft bar.
+
 Stuck, or the human is unhappy with a result? instructions/reference/ holds the deep
 guides (layout, typography, color, motion, copy, states, tuning, critique, concepts) -
 the routing index is at the top of instructions/craft.md. Pull ONE file, apply, return.
@@ -32,7 +41,8 @@ the routing index is at the top of instructions/craft.md. Pull ONE file, apply,
   export const meta = { title: "...", viewport: "mobile" }   // literal values only
   // viewport names come from design/config.ts (default: mobile, tablet, laptop, monitor;
   // tv available commented-out). Pick the one the screen is designed for - the human can
-  // flip the whole board to any device (Devices menu, hotkeys 0-5) to check responsiveness.
+  // flip the whole board to any device (Devices menu; digit keys - 0 restores each
+  // frame's own size, 1..n per configured device) to check responsiveness.
 - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
 - VERSIONS are sibling frames with letter prefixes, and the canvas understands them:
   design/scenes/landing/a-terminal.tsx + b-editorial.tsx form a VARIANT GROUP - kept

package/templates/instructions/configure.md

@@ -20,9 +20,12 @@ All four true → idle state. Go design.
 
 ## By repo maturity
 
+The human's first session layers on top of this: philosophy, their product on the
+canvas, the tour - that flow lives in instructions/welcome.md, run it alongside.
+
 - **Brand-new repo (no app)**: `design/instructions/setup.md` exists and is the
-  authority - STOP, follow it (set up the stack, re-run init). Do not design against
-  a repo that has nothing to build from.
+  authority - follow it (set up the stack WITH the human, re-run init). Do not
+  design against a repo that has nothing to build from.
 - **Fresh repo (app scaffolded, little product code)**: init's detection is usually
   right. Verify the checklist, create DESIGN.md from the starter tokens (Path A -
   even a default shadcn theme is a documentable brand), and note in it which parts

package/templates/instructions/discover.md

@@ -2,7 +2,8 @@
 
 Run this phase for any NEW surface, feature, or project. Skip it only when a brief
 already answers everything below. Its output is a written brief; nothing gets designed
-until the brief has a human nod.
+until the brief has a human nod. (One exception: the first-session draft
+(welcome.md) skips the brief - the human just said what they are building.)
 
 ## 1. Read the repo, then interview
 

package/templates/instructions/welcome.md

@@ -0,0 +1,122 @@
+# Welcome - the human's first session
+
+Run this the FIRST time you work with the human in a repo, or whenever they ask
+what marver is or how it works. Unsure whether they were already welcomed? If
+design/DESIGN.md is missing or no curated board exists yet, treat it as not
+yet. The job: by the end of the session the human understands the tool, has
+seen their own product on the canvas, and knows what to do next. Narrate as you
+go - one short plain sentence per step, teaching by doing, never a lecture.
+
+## Voice - tell the story, not the machinery
+
+These instruction files are stage directions, not a script to read aloud. Never
+narrate them to the human ("setup.md says...", "step 2 requires...", "per the
+generated instructions I must...") - speak as a designer who is excited to
+start: what we're doing, why it matters, what comes next. Intent over
+internals; one warm, concrete sentence beats three procedural ones.
+
+- Robotic: "Init flagged that there's no app yet and pointed me to setup.md.
+  I'm following that file now, and step one is a conversation with you."
+- Human: "Canvas is in. Before anything gets built I want to know what we're
+  making - that decides everything else."
+
+Precision still matters - engineers are reading - but the file paths, step
+numbers, and phase names are yours, not theirs.
+
+When you ask the human to choose (the stack, a variant direction), use your
+harness's structured question tool (AskUserQuestion or similar) if one exists -
+short option labels, one-line trade-offs, and a small ASCII sketch per option
+when the choice is visual. Plain prose is the fallback, never the preference.
+Asking through the tool IS the stop: no further tool calls after it, wait for
+the answer.
+
+## The pitch (say it early, in your own words)
+
+marver co-designs the user experience with the human in real code. Frames are
+not mockups - they are components using the app's actual theme and component
+library. The theme, components, and screens shaped while designing ARE the
+app's building blocks: by the time the design is agreed, most of the UI work
+already exists, and building the product means plugging functionality into it.
+The goal is full alignment on look and feel - across light and dark, across
+every device size - before app logic is written.
+
+## Empty repo?
+
+design/instructions/setup.md is the authority (it exists only while the repo
+has no app). Follow it end to end; it sends you back here for the reveal.
+
+## The waiting room - hand them the hosted tour while you build
+
+Building well takes real minutes, and the human should spend them inside a
+canvas, not watching a terminal. The moment the plan is agreed (the stack nod,
+or the Path B confirmation below), send them to the marver tour - a published
+canvas made to be explored: https://tour.marver.design - password `welcome`.
+It teaches selection, devices, themes, variants, and play mode from inside the
+frames, and it ends by sending them back to check on your work. Then build
+without narrating into the void; your next message is the reveal.
+
+## Existing codebase - first session flow
+
+1. **Say what the app is.** Read the repo (entry point, routes, key screens).
+   State your understanding of the product in 2-3 sentences, ask "did I get
+   that right?" - then STOP: no further tool calls, end your turn, resume when
+   the human replies. (Only exception: they explicitly asked for unattended
+   execution - assume, mark UNCONFIRMED, surface it first.)
+2. **Confirm the stack aloud - what detection ACTUALLY found.** Read AGENTS.md's
+   UI line and design/theme.css and narrate the reality, for example: "Tailwind
+   + shadcn/ui; brand tokens in <file>; design/theme.css imports them." No
+   component library? Say that, and what it means (shared pieces get extracted
+   to design/components/). Anything wrong gets fixed now, while it is cheap
+   (configure.md, old-repo checklist). Once confirmed, hand them the hosted
+   tour (the waiting room above) and get to work.
+3. **Put THEIR product on the canvas - impressively.** Recreate 3-4 of the
+   app's real screens as frames from its real components, linked with data-goto
+   so play mode flows, working in both themes, responsive. This is the human's
+   first impression of the canvas: hold it to the craft bar
+   (instructions/craft.md, instructions/reference/slop.md). Create a curated
+   board for the set. First sessions skip the written-brief ceremony, never the
+   quality bar; real work after the tour runs the full method ladder.
+4. **Explain the working model while building:** existing components are reused
+   as-is; missing pieces are created as presentational components - fixture
+   props, placeholder handlers - and get real wiring at promotion (where they
+   live is AGENTS.md's structure ladder). Look and feel converges first;
+   production becomes plugging functionality into agreed UI.
+5. **Offer a divergence.** "Want a variant of <frame> exploring a different
+   direction?" One a-/b- pair teaches the variant workflow better than any
+   explanation.
+6. **Give the tour** (below), ending with the deep link.
+
+## The reveal
+
+Deliver conversationally when the first draft is ready - a short guided
+message, not a manual. Start `npx marver dev` if it is not already running
+(allowed for this purpose) and ALWAYS hand a deep link to the board you
+prepared, using the port the dev server PRINTED:
+`http://localhost:<port>/#/b/<board>` - never the bare root URL. The link goes
+at the BOTTOM of the message, on its own line: the human reads through, then
+clicks. The human has already played with the hosted tour by now, so keep it
+short - let their own product carry the moment. The highlights, all real
+features:
+
+- **Select and preview.** Click frames (shift-click for several). Digit keys
+  switch device presets - 1-4 for the configured devices, 0 back to each
+  frame's own size - scoped to the selection when one exists, the whole board
+  otherwise. `d` cycles light/dark the same way: selected frames, or the
+  entire canvas view (frames pinned to a theme in their meta stay put).
+- **Touch it.** Double-click a frame - the purple ring is interact mode: the
+  frame is live, clickable, scrollable.
+- **Play it.** `p` opens play mode: the design full screen in a device, with
+  data-goto links navigating between frames like the real app. `[` and `]`
+  switch variants in place; devices switch inside play too, including
+  full-screen fill.
+- **Explore alternatives.** Letter-prefixed sibling files (a-bold.tsx,
+  b-minimal.tsx) form a variant group - badged, kept contiguous, compared at a
+  glance. The cheap way to diverge on a direction before committing.
+- **Compose.** `t` re-tidies; boards carry a `layout` recipe for deliberate
+  arrangement (instructions/boards.md).
+- **Share it.** `marver build` bundles the boards; `marver serve` with
+  MARVER_PASSWORD on any Node host (Railway, Fly, a VPS) publishes them as a
+  password-gated canvas the human owns - colleagues get the link plus the
+  password. Comments on the board are coming soon.
+
+Close by asking what they want to design first.