@marver-design/marver 0.2.1 → 0.2.2

package/README.md

@@ -18,6 +18,7 @@ Then, to your agent:
 - **Boards**: one canvas on screen at a time. Agents write `design/boards/<name>.json` (a frame list is enough); switch boards at the top of the sidebar. `all-scenes` is auto-managed.
 - **Devices view**: the Devices menu (or hotkeys `1`-`5`) sizes every frame to mobile / tablet / laptop / monitor / tv to sweep your breakpoints; `0` restores your own layout exactly. Widths live in `design/config.ts`.
 - `data-goto="scene/frame"` on any element links frames into a walkable prototype.
+- **Upgrade**: `npm i -D @marver-design/marver@latest && npx marver init`. The canvas tells you when a new version is out (one anonymous registry check per day, cached in `design/.local/`; `MARVER_NO_UPDATE_CHECK=1` disables). Re-running init refreshes the managed files (AGENTS.md, `design/instructions/`) - your edits to them are detected and preserved; when both you and a release changed a file, the fresh version is staged at `design/.local/latest/` for you (or your agent) to merge. Everything else in `design/` is yours and never touched.
 - Uninstall: delete `design/`, remove the dependency. (If `init` patched your tsconfig `exclude`, revert that one line.)
 
 **Next.js**: supported with one caveat - frames render in Vite, outside Next. `next/font` CSS variables are undefined inside frames (give font tokens a fallback chain), `next/image`/`next/link` should be plain `img`/`data-goto` in frames, and Server Components cannot run there. `init` writes the specifics into `design/AGENTS.md` when it detects Next.

package/dist/{build-BYZDMiIS.mjs → build-CNoXE13J.mjs}

@@ -1,6 +1,6 @@
 import { r as ROUTE, t as NAME } from "./cli.mjs";
 import { a as loadConfig, n as scanFrames, o as detectHost } from "./manifest-CHmKAAtG.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-lVQoABEx.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DiDJA9n-.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/cli.mjs

@@ -32,14 +32,14 @@ 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-CHUZTYG7.mjs");
+	const { init } = await import("./init-3h9pXEzp.mjs");
 	init(resolve(opts.root), {
 		mode: opts.mode === "embedded" ? "embedded" : "studio",
 		demo: opts.demo !== false
 	});
 });
 cli.command("dev", "Start the canvas").option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default 5199)").action(async (opts) => {
-	const { dev } = await import("./dev-Dt9D4O7Z.mjs");
+	const { dev } = await import("./dev-Blyy4jOL.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -49,7 +49,7 @@ cli.command("dev", "Start the canvas").option("--root <dir>", "Host repo root",
 	await dev(resolve(opts.root), port);
 });
 cli.command("build", "Static export → design/.dist").option("--boards <names>", "Publish only these boards (comma-separated); the frame filter is applied at build time").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-BYZDMiIS.mjs");
+	const { buildSite } = await import("./build-CNoXE13J.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve(opts.root), boards);

package/dist/{dev-Dt9D4O7Z.mjs → dev-Blyy4jOL.mjs}

@@ -1,6 +1,6 @@
 import { n as PKG, t as NAME } from "./cli.mjs";
 import { a as loadConfig, o as detectHost } from "./manifest-CHmKAAtG.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-lVQoABEx.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DiDJA9n-.mjs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createLogger, createServer, searchForWorkspaceRoot } from "vite";

package/dist/{init-CHUZTYG7.mjs → init-3h9pXEzp.mjs}

@@ -1,16 +1,45 @@
 import { t as NAME } from "./cli.mjs";
 import { i as DEFAULTS, n as scanFrames, o as detectHost, r as writeManifest } from "./manifest-CHmKAAtG.mjs";
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
 //#region src/cli/init.ts
-const pkgDir = () => join(dirname(fileURLToPath(import.meta.url)), "..");
+/** Package root = the nearest ancestor holding templates/ (one hop from dist/, two
+*  from src/cli/ - the walk serves both, and tests run init from source). */
+const pkgDir = () => {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 4; i++) {
+		if (existsSync(join(dir, "templates"))) return dir;
+		dir = dirname(dir);
+	}
+	return join(dirname(fileURLToPath(import.meta.url)), "..");
+};
 /** Idempotent scaffolder: never overwrites existing files; every host-repo touch prints a diff. */
 function init(root, opts) {
 	const host = detectHost(root);
 	const design = join(root, "design");
 	const templates = join(pkgDir(), "templates");
 	const created = [];
+	const fileHas = (rel, needle) => {
+		try {
+			return readFileSync(join(design, rel), "utf8").includes(needle);
+		} catch {
+			return false;
+		}
+	};
+	const marverShaped = fileHas("config.ts", "marver") || fileHas("AGENTS.md", "agent contract");
+	if (existsSync(design) && !marverShaped && readdirSync(design).some((f) => !f.startsWith("."))) {
+		console.error(`
+[${NAME}] design/ already exists in this repo and does not look like a ${NAME} workspace.
+         Refusing to merge into it - your files and ${NAME}'s would interleave, and
+         "uninstall = delete design/" would stop being safe.
+
+         Move or rename the existing design/ folder, then re-run \`npx ${NAME} init\`.
+         (If you need marver to live in a differently-named folder, say so at
+         github.com/TNEP4/marver - a --dir flag is planned.)`);
+		process.exit(1);
+	}
 	const write = (rel, content) => {
 		const file = join(design, rel);
 		if (existsSync(file)) return;
@@ -18,21 +47,70 @@ function init(root, opts) {
 		writeFileSync(file, content);
 		created.push(`design/${rel}`);
 	};
+	const writeManaged = (rel, body) => {
+		const file = join(design, rel);
+		const next = managedFile(body);
+		const latest = join(design, ".local", "latest", rel);
+		if (!existsSync(file)) return write(rel, next);
+		const current = readFileSync(file, "utf8");
+		if (current === next) {
+			rmSync(latest, { force: true });
+			return;
+		}
+		if (current.startsWith(MANAGED_PREFIX)) {
+			const recorded = current.slice(MANAGED_PREFIX.length).split(" ")[0];
+			const nl = current.indexOf("\n");
+			const currentBody = nl >= 0 ? current.slice(nl + 1) : "";
+			if (nl >= 0 && hashBody(currentBody) === recorded) {
+				writeFileSync(file, next);
+				rmSync(latest, { force: true });
+				created.push(`design/${rel} (updated)`);
+			} else if (recorded !== hashBody(body)) {
+				mkdirSync(dirname(latest), { recursive: true });
+				writeFileSync(latest, body);
+				if (nl >= 0) {
+					const tmp = file + ".tmp";
+					writeFileSync(tmp, managedFile(body).split("\n")[0] + "\n" + currentBody);
+					renameSync(tmp, file);
+				}
+				console.warn(`  ~ design/${rel}: you customized it and a newer version exists - your edits are untouched. Merge what you want from design/.local/latest/${rel}`);
+			}
+		} else if (current.startsWith(LEGACY_PREFIX)) {
+			writeFileSync(file, next);
+			rmSync(latest, { force: true });
+			created.push(`design/${rel} (updated)`);
+		} else if (current !== body) {
+			rmSync(latest, { force: true });
+			console.warn(`  note: design/${rel} exists without a marver marker - left untouched. If you did not author it, delete it and re-run init to restore the managed version.`);
+		}
+	};
 	write("config.ts", configTemplate(opts.mode));
 	if (host.themeCss) {
 		const relCss = relative(design, join(root, host.themeCss)).split("\\").join("/");
 		write("theme.css", themeWrapper(relCss, host.tailwind === 4));
 	} else console.warn(`[${NAME}] no theme CSS detected - create design/theme.css importing your app's stylesheet when you have one (or set \`theme\` in design/config.ts).`);
 	write("providers.tsx", providersTemplate(host.router, host.toaster, host.routerPkg));
-	const agents = AGENTS_MARKER + "\n" + readFileSync(join(templates, `AGENTS-${opts.mode}.md`), "utf8").replaceAll("{{UI_GUIDANCE}}", uiGuidance(host)).replace(/\{\{NEXT_NOTES\}\}\n?/, host.router === "next" ? NEXT_NOTES : "");
-	const agentsPath = join(design, "AGENTS.md");
-	if (!existsSync(agentsPath)) write("AGENTS.md", agents);
-	else {
-		const current = readFileSync(agentsPath, "utf8");
-		if (current.startsWith(AGENTS_MARKER) && current !== agents) {
-			writeFileSync(agentsPath, agents);
-			created.push("design/AGENTS.md (regenerated - detected stack changed)");
+	writeManaged("AGENTS.md", readFileSync(join(templates, `AGENTS-${opts.mode}.md`), "utf8").replaceAll("{{UI_GUIDANCE}}", uiGuidance(host, noApp(host))).replace(/\{\{NEXT_NOTES\}\}\n?/, host.router === "next" ? NEXT_NOTES : ""));
+	const agentsNow = readFileSync(join(design, "AGENTS.md"), "utf8");
+	if (!agentsNow.startsWith(MANAGED_PREFIX) && !agentsNow.startsWith(LEGACY_PREFIX) && agentsNow.includes("# Design canvas - agent contract") && !agentsNow.includes("## The method (binding)")) console.warn(`  note: design/AGENTS.md predates managed regeneration - if you never edited it, delete it and re-run init to get the current contract (incl. the design/instructions routing).`);
+	const instrRoot = join(templates, "instructions");
+	for (const e of readdirSync(instrRoot, { withFileTypes: true })) if (e.isDirectory()) {
+		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;
 		}
+	};
+	if (noApp(host)) {
+		if (!existsSync(setupPath)) write("instructions/setup.md", SETUP_MD);
+	} else if (existsSync(setupPath) && ourSetup()) {
+		rmSync(setupPath);
+		console.log(`  - design/instructions/setup.md removed (app detected - setup complete)`);
 	}
 	write("tsconfig.json", existsSync(join(root, "tsconfig.json")) ? readFileSync(join(templates, "design-tsconfig.json"), "utf8") : STANDALONE_TSCONFIG);
 	write(".gitignore", ".local/\n.dist/\n");
@@ -53,32 +131,67 @@ function init(root, opts) {
 	if (host.router === "next") console.log(`\n  note: Next.js support is partial - frames render outside Next, so next/font, next/image and Server Components do not exist inside them (details in design/AGENTS.md).`);
 	if (noApp(host)) console.warn(`
   ┌─ NO APP DETECTED ─────────────────────────────────────────────────────┐
-  │ This repo has no framework, no theme CSS, and no component library.   │
-  │ ${NAME} builds frames from YOUR components - with none, frames become │
-  │ hand-rolled CSS that cannot be promoted into an app later.            │
+  │ No framework, no theme CSS, no component library. ${NAME} builds      │
+  │ frames from YOUR components - with none, designs get thrown away.     │
   │                                                                       │
-  │ Set up the app first, then re-run init (it is idempotent and will     │
-  │ fill in what it detects). For a web app or site:                      │
-  │   npx create-next-app@latest . --ts --tailwind --app --src-dir        │
-  │   npx shadcn@latest init                                              │
-  │                                                                       │
-  │ design/AGENTS.md was generated with a STOP instruction so your agent  │
-  │ does not design against a component library that does not exist.     │
+  │ 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.   │
   └───────────────────────────────────────────────────────────────────────┘`);
 	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" : ""}`);
 	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`);
 }
-const AGENTS_MARKER = "<!-- generated by marver init from the detected stack; re-running init regenerates this file when detection changes. Made edits you want to keep? Delete this line and init will never touch the file again. -->";
+const MANAGED_PREFIX = "<!-- marver:managed ";
+const LEGACY_PREFIX = "<!-- generated by marver init";
+const hashBody = (s) => createHash("sha256").update(s).digest("hex");
+/** The marker carries a hash of the generated body: edits are DETECTED, not assumed.
+*  Edit freely - init preserves edits and stages upstream updates for merging.
+*  Deleting the marker line detaches the file from updates entirely. */
+const managedFile = (body) => `${MANAGED_PREFIX}${hashBody(body)} - edit freely: init preserves your edits and stages upstream updates at design/.local/latest/ for you to merge. Delete this line to detach this file from updates entirely. -->\n${body}`;
 /** No framework, no theme, no component alias = nothing to build frames FROM. */
 const noApp = (host) => !host.router && !host.tailwind && !host.shadcn && !host.themeCss;
-/** The UI line of AGENTS.md, matched to what detection actually found (friction log #1). */
-function uiGuidance(host) {
+/** The UI line of AGENTS.md, matched to what detection actually found (friction log #1).
+*  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 (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 `STOP - this repo has no component library, no Tailwind, and no theme. Frames built from hand-rolled CSS cannot be promoted into an app later. Ask the human to set up the app first (framework + styling), then re-run \`npx ${NAME} init\` so this contract regenerates against the real stack.`;
+	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/.`;
 }
+const SETUP_MD = `# Setup required - this repo has no app yet
+
+> This file exists because \`${NAME} init\` ran in a repo with no framework, no theme
+> CSS, and no component library. It disappears automatically: set up the app, re-run
+> \`npx ${NAME} init\`, and init deletes this file and regenerates AGENTS.md against
+> 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.
+
+## Do this first
+
+For a web app or marketing site, the blessed stack:
+
+\`\`\`bash
+npx create-next-app@latest . --ts --tailwind --app --src-dir
+npx shadcn@latest init
+\`\`\`
+
+Any React + CSS setup works; the point is that components and a theme EXIST.
+
+## Then
+
+\`\`\`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.
+`;
 /** 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):
   next/font does not exist here - CSS variables it injects (e.g. --font-geist-sans) are

package/dist/{plugin-lVQoABEx.mjs → plugin-DiDJA9n-.mjs}

@@ -1,7 +1,8 @@
-import { r as ROUTE } from "./cli.mjs";
+import { n as PKG, r as ROUTE, t as NAME } from "./cli.mjs";
 import { n as scanFrames, r as writeManifest, t as hash } from "./manifest-CHmKAAtG.mjs";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 //#region src/server/api.ts
 const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
@@ -185,6 +186,73 @@ function routesMiddleware(server, clientDir) {
 	};
 }
 //#endregion
+//#region src/server/update.ts
+/**
+* Update discovery - dev only, and deliberately boring about privacy: one anonymous
+* registry metadata GET per day (the same request `npm view` makes), cached in
+* design/.local/, nothing sent beyond the request itself. Offline, slow, or
+* firewalled registries degrade to silence. MARVER_NO_UPDATE_CHECK=1 disables it.
+* Published bundles never check anything - viewers are not the owner.
+*/
+const TTL = 864e5;
+/** Installed version: walk up from this module to the package's own package.json
+*  (one level from dist/, two from src/server/ - the walk covers both). */
+function installedVersion() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 4; i++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (pkg.name === "@marver-design/marver") return pkg.version;
+		} catch {}
+		dir = dirname(dir);
+	}
+	return null;
+}
+/** Strictly-newer numeric compare; anything non-numeric (prerelease tags) compares false. */
+const newer = (a, b) => {
+	const pa = a.split(".").map((n) => parseInt(n, 10));
+	const pb = b.split(".").map((n) => parseInt(n, 10));
+	for (let i = 0; i < 3; i++) {
+		const x = pa[i] ?? 0, y = pb[i] ?? 0;
+		if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+		if (x !== y) return x > y;
+	}
+	return false;
+};
+/** The latest published version when strictly newer than installed, else null. Never throws. */
+async function checkUpdate(root) {
+	if (process.env.MARVER_NO_UPDATE_CHECK) return null;
+	const current = installedVersion();
+	if (!current) return null;
+	const latest = await latestVersion(root);
+	return latest && newer(latest, current) ? latest : null;
+}
+async function latestVersion(root) {
+	const cacheFile = join(root, "design", ".local", "update-check.json");
+	const wellFormed = (v) => typeof v === "string" && /^\d+\.\d+\.\d+$/.test(v);
+	try {
+		const c = JSON.parse(readFileSync(cacheFile, "utf8"));
+		const age = Date.now() - c.checkedAt;
+		if (typeof c.checkedAt === "number" && age >= 0 && age < TTL) return wellFormed(c.latest) ? c.latest : null;
+	} catch {}
+	let latest = null;
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PKG)}/latest`, { signal: AbortSignal.timeout(3e3) });
+		if (res.ok) {
+			const v = (await res.json())?.version;
+			if (wellFormed(v)) latest = v;
+		}
+	} catch {}
+	try {
+		mkdirSync(join(root, "design", ".local"), { recursive: true });
+		writeFileSync(cacheFile, JSON.stringify({
+			checkedAt: Date.now(),
+			latest
+		}) + "\n");
+	} catch {}
+	return latest;
+}
+//#endregion
 //#region src/server/plugin.ts
 const VIRTUAL_THEME = "virtual:sh-theme";
 const VIRTUAL_CONFIG = "virtual:sh-config";
@@ -211,12 +279,23 @@ function marverPlugin(ctx) {
 				console.warn("[marver] no theme detected - frames render unstyled. Create design/theme.css importing your app's stylesheet (or set `theme` in design/config.ts).");
 				return "/* marver: no theme configured */";
 			}
-			if (id === "\0virtual:sh-config") return `export default ${JSON.stringify({
-				viewports: config.viewports,
-				themes: config.themes,
-				zoomSpeed: config.zoomSpeed,
-				noTheme: themeFile() == null
-			})}`;
+			if (id === "\0virtual:sh-config") {
+				const setupPending = (() => {
+					try {
+						const s = readFileSync(join(root, "design", "instructions", "setup.md"), "utf8");
+						return s.startsWith("# Setup required") && s.includes("marver init");
+					} catch {
+						return false;
+					}
+				})();
+				return `export default ${JSON.stringify({
+					viewports: config.viewports,
+					themes: config.themes,
+					zoomSpeed: config.zoomSpeed,
+					noTheme: themeFile() == null,
+					setup: setupPending
+				})}`;
+			}
 			if (id === "\0virtual:sh-data") return "export default null";
 		},
 		/** HTML frames: inject theme + bridge into any design/**.html Vite serves.
@@ -263,6 +342,21 @@ function marverPlugin(ctx) {
 				}
 				next();
 			});
+			const update = checkUpdate(root).catch(() => null);
+			update.then((latest) => {
+				if (latest) console.log(`\n  update: ${PKG} ${latest} is out (installed ${installedVersion() ?? "?"}) → npm i -D ${PKG}@latest && npx ${NAME} init\n`);
+			});
+			server.middlewares.use((req, res, next) => {
+				if (new URL(req.url ?? "/", "http://x").pathname !== `/__mv/api/update`) return next();
+				update.then((latest) => {
+					res.setHeader("content-type", "application/json");
+					res.setHeader("cache-control", "no-store");
+					res.end(JSON.stringify({
+						latest,
+						current: installedVersion()
+					}));
+				});
+			});
 			server.middlewares.use(apiMiddleware(root));
 			server.middlewares.use(routesMiddleware(server, clientDir));
 			const regen = debounce(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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/src/client/shell/App.tsx

@@ -1,12 +1,12 @@
 import { Component, useEffect, useRef, useState, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
-import { useStore, CONFIG, boardLabel, cap, fetchBoardNames } from './store.ts'
+import { useStore, CONFIG, PUBLISHED, boardLabel, cap, fetchBoardNames } from './store.ts'
 import { Tip } from './Tip.tsx'
-import { ROUTE } from '../const.ts'
+import { PKG, ROUTE } from '../const.ts'
 import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
 import { enterPlay, playCtl, PlayOverlay } from './Play.tsx'
 import { bootHash, parseHash, writeHash } from './hash.ts'
-import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, DevicesIcon, GridIcon, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, PlayIcon, PlusIcon, SignpostIcon, SunIcon, deviceIcon } from './icons.tsx'
+import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, DevicesIcon, GridIcon, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, PlayIcon, PlusIcon, SignpostIcon, SunIcon, XIcon, deviceIcon } from './icons.tsx'
 
 let booted = false                             // survives Fast Refresh; see the boot effect
 
@@ -251,6 +251,45 @@ function DeviceMenu() {
   )
 }
 
+/** Update pill (dev only): the daily registry check surfaces here - same glass, same
+ *  pill, bottom-center. Click the command to copy it; × dismisses THIS version for
+ *  good (localStorage), so the pill returns only when the next release lands. */
+function UpdatePill() {
+  const [latest, setLatest] = useState<string | null>(null)
+  const play = useStore((s) => s.play)
+  useEffect(() => {
+    if (PUBLISHED) return                     // a shared canvas never nags its viewers
+    fetch(`${ROUTE}/api/update`)
+      .then((r) => (r.ok ? r.json() : null))
+      .then((u) => {
+        if (u?.latest && localStorage.getItem('mv-update-seen') !== u.latest) setLatest(u.latest)
+      })
+      .catch(() => { /* dev server gone or endpoint absent - stay quiet */ })
+  }, [])
+  if (!latest || play) return null
+  // init rides along so managed files (AGENTS.md, instructions/) refresh with the code
+  const cmd = `npm i -D ${PKG}@latest && npx marver init`
+  const dismiss = () => {
+    try { localStorage.setItem('mv-update-seen', latest) } catch { /* storage unavailable */ }
+    setLatest(null)
+  }
+  return (
+    <div className="sh-update">
+      <span><b>{latest}</b> is out</span>
+      <Tip side="top" label="Copy, then paste to your terminal or your agent">
+        <button className="cmd" onClick={() => {
+          const t = useStore.getState().toast
+          navigator.clipboard?.writeText(cmd).then(() => t('update command copied'), () => t('copy blocked - select it manually'))
+            ?? t('copy unavailable - select it manually')
+        }}><code>{cmd}</code></button>
+      </Tip>
+      <Tip side="top" label="Dismiss this version">
+        <button className="x" onClick={dismiss}><XIcon size={13} /></button>
+      </Tip>
+    </div>
+  )
+}
+
 const ZOOMS = [2, 1.5, 1, 0.5, 0.25, 0.1]
 
 /** Zoom preset dropdown on the percentage readout. */
@@ -642,7 +681,10 @@ export function App() {
 
       <PlayOverlay />
 
-      {CONFIG.noTheme && <div className="sh-banner">no theme configured - frames render unstyled. Create design/theme.css importing your app's stylesheet (or set theme in design/config.ts)</div>}
+      {CONFIG.setup
+        ? <div className="sh-banner">no app detected - designs would be built from nothing. See design/instructions/setup.md, then restart</div>
+        : CONFIG.noTheme && <div className="sh-banner">no theme configured - frames render unstyled. Create design/theme.css importing your app's stylesheet (or set theme in design/config.ts)</div>}
+      <UpdatePill />
 
       <div className="sh-toasts">
         {toasts.map((t) => <div key={t.id} className="sh-toast"><CheckIcon size={12} /> {t.text}</div>)}

package/src/client/shell/store.ts

@@ -11,6 +11,9 @@ import shData from 'virtual:sh-data'
  *  is where `/` opens - never a synthesized aggregate of a filtered build. */
 const DATA: { manifest: Manifest; boards: Record<string, unknown>; names: string[]; default: string } | null = shData
 
+/** True on a published static canvas - no dev server, no API, no update checks. */
+export const PUBLISHED = DATA !== null
+
 export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string }
 export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number }[] }
 export interface Node {
@@ -27,7 +30,7 @@ export interface Node {
 }
 export interface Toast { id: number; text: string }
 
-export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean } = shConfig
+export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean } = shConfig
 
 export const cap = (s: string) => (s ? s[0].toUpperCase() + s.slice(1) : s)
 

package/src/client/shell/styles.css

@@ -194,7 +194,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .sh-handle.se { right: -5px; bottom: -5px; width: 11px; height: 11px; cursor: nwse-resize }
 
 /* glass surfaces share one recipe; chrome text is never selectable (shift-click = multi-select) */
-.sh-ctx, .sh-panel, .sh-fab, .sh-pill, .sh-pill-fab, .sh-menu, .sh-banner, .sh-toast {
+.sh-ctx, .sh-panel, .sh-fab, .sh-pill, .sh-pill-fab, .sh-menu, .sh-banner, .sh-toast, .sh-update {
   background: var(--glass); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
   border: 1px solid var(--glass-brd); box-shadow: var(--shadow-glass); position: relative;
   user-select: none; -webkit-user-select: none }
@@ -202,7 +202,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 /* edge light: a 1px gradient ring over the border, so glass reads as glass even
    with nothing behind it to blur (masked-border technique) */
 .sh-ctx::after, .sh-panel::after, .sh-fab::after, .sh-pill::after, .sh-pill-fab::after,
-.sh-menu::after, .sh-banner::after, .sh-toast::after, .sh-node::after {
+.sh-menu::after, .sh-banner::after, .sh-toast::after, .sh-update::after, .sh-node::after {
   content: ''; position: absolute; inset: -1px; padding: 1px; border-radius: inherit;
   background: var(--edge-light); pointer-events: none;
   -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
@@ -404,6 +404,25 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .sh-banner { position: absolute; bottom: var(--edge); right: var(--edge); z-index: 10; font: 500 12px -apple-system, system-ui, sans-serif;
   color: var(--glass-warn); border-radius: 999px; padding: 8px 14px }
 
+/* update pill: bottom-center, the quietest possible member of the pill family.
+   The command IS the button - one click copies it for the terminal or the agent. */
+.sh-update { position: absolute; left: 50%; bottom: var(--edge); transform: translateX(-50%); z-index: 10;
+  display: flex; align-items: center; gap: 10px; height: 40px; padding: 0 7px 0 16px; border-radius: 999px;
+  max-width: min(92vw, 620px); white-space: nowrap;
+  font: 500 12.5px -apple-system, system-ui, sans-serif; color: var(--glass-ink-2);
+  animation: sh-update-in .35s cubic-bezier(.2, .9, .3, 1.2) }
+@keyframes sh-update-in { from { opacity: 0; transform: translate(-50%, 8px) scale(.96) } }
+.sh-update b { font-weight: 650; color: var(--glass-ink) }
+.sh-update .cmd { border: 1px solid var(--glass-brd); background: var(--glass-hover); border-radius: 999px;
+  padding: 4px 11px; cursor: pointer; min-width: 0; overflow: hidden; transition: color .15s }
+.sh-update .cmd code { font: 500 11.5px ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--glass-ink-2);
+  display: block; overflow: hidden; text-overflow: ellipsis }
+.sh-update .cmd:hover code { color: var(--glass-ink) }
+.sh-update .x { display: inline-flex; align-items: center; justify-content: center; width: 26px; height: 26px;
+  border: 0; background: none; border-radius: 999px; color: var(--glass-ink-3); cursor: pointer;
+  transition: color .15s, background .15s }
+.sh-update .x:hover { background: var(--glass-hover); color: var(--glass-ink) }
+
 .sh-toasts { position: absolute; left: var(--edge); bottom: var(--edge); z-index: 12; display: flex; flex-direction: column; gap: 6px }
 .sh-toast { display: flex; align-items: center; gap: 6px; font: 500 12px -apple-system, system-ui, sans-serif;
   color: var(--glass-ink-2); border-radius: 999px; padding: 7px 13px }

package/templates/AGENTS-embedded.md

@@ -3,6 +3,29 @@
 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.
 
+## The method (binding)
+
+Design work moves through phases. BEFORE working in a phase, read its instruction
+file in design/instructions/ - they are short, strict, and part of this contract:
+
+| Phase | When | Read |
+|---|---|---|
+| 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 |
+| Brand | before the first hi-fi work: extract or create the world | instructions/brand.md |
+| Build | hi-fi frames from real components | instructions/craft.md + components.md |
+| Review | before presenting anything | instructions/review.md |
+| Boards | creating a board or publishing | instructions/boards.md |
+
+Refining an existing screen: Configure must hold, then Build + Review. New work runs
+the full ladder. Unsure which phase you are in? Ask the human - one question beats a
+phase of wrong work.
+
+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.
+
 ## Frames
 - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
 - It default-exports a React component. No imports from the tool are needed. Optional:
@@ -35,7 +58,7 @@ Never run or talk to the canvas tool; read and write files only.
    convention). The root design/scenes/_layout.tsx mounts the app's real shell component.
 
 ## Fixtures
-- design/scenes/<scene>/_fixtures.ts - typed plain objects shaped like the future API.
+- design/scenes/<scene>/_fixtures.ts - typed plain objects shaped like the component's PROPS (containers map real APIs into them at promotion; see instructions/components.md).
 - Fixture shapes should match the component's props so tsc catches drift.
 - Loading states are fixtures too: export const slowOrders = () => new Promise(r =>
   setTimeout(() => r(orders), 800)) and let the frame render its skeleton while awaiting.
@@ -59,29 +82,7 @@ Never run or talk to the canvas tool; read and write files only.
 
 ## Boards (curated canvases)
 
-A board is a saved canvas: `design/boards/<name>.json` (name: `^[a-z0-9][a-z0-9-]*$`).
-The human switches boards in the sidebar; YOU create and manage them by writing files.
-Minimal file - just list the frames; the shell fills sizes from each frame's viewport,
-lays it out, and keeps it tidy:
-
-```json
-{ "version": 1, "name": "checkout-compare", "auto": false,
-  "nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
-```
-
-- The same frame may appear on many boards, or twice on one board (e.g. two widths:
-  add `"w"`/`"h"` on a node to pin a size, `"x"`/`"y"` to place it - e.g. a comparison
-  row: same `y`, increasing `x`). Know that the human's tidy (`t`) and device views
-  re-layout in frame-id order, so id ordering is the durable arrangement; explicit
-  coordinates are for one-off setups.
-- `auto: false` boards show exactly their list. The `all-scenes` board is auto-managed -
-  never write it.
-- Use boards for comparisons: version A vs B vs C of a flow, side by side.
-- Boards are also the unit of PUBLISHING (`marver build --boards <name>`): a flow being
-  published must have every frame it data-gotos on that board - unlisted frames are
-  excluded from the bundle at build time. The published gate page shows the app's
-  identity: design/logo.svg + the host package name (overridable via config `share`).
-  If the app has no logo asset yet, create a simple design/logo.svg for it.
-  Leave `share.branding` ON unless the human explicitly asks to remove it: Marver is
-  free, the gate is already fully personalized to the app, and the small "Powered by"
-  line is how the tool spreads. Do not remove it as part of "branding polish".
+A board is a saved canvas: `design/boards/<name>.json` - you create and manage them
+by writing files; `all-scenes` is auto-managed, never write it. BEFORE creating a
+board or publishing anything, read instructions/boards.md (file format, layout
+durability, publishing rules).