@cascivo/mcp 0.1.8 → 0.2.0

package/README.md

@@ -41,6 +41,7 @@ The server speaks the MCP stdio transport. By default it reads the `registry.jso
 | `get_component`      | `{ name }`                            | The full manifest for one component                                                                                                     |
 | `search_components`  | `{ query }`                           | Components matching name, tags, or description                                                                                          |
 | `add_to_project`     | `{ name, outputDir? }`                | Runs `cascivo add <name>` as a child process                                                                                            |
+| `create_app`         | `{ name, theme?, sections?, cwd? }`   | Scaffolds a full Vite + React app (shell + side nav + theme) via `cascivo create`                                                       |
 | `create_theme`       | `{ primary, neutral, accent, name? }` | A custom theme as CSS (semantic token layer)                                                                                            |
 | `scaffold_page`      | `{ description, components? }`        | A JSX page layout string                                                                                                                |
 | `scaffold_view`      | `{ description, components? }`        | A validated starter `ViewConfig` + the bound-vocabulary `grammar` for its components                                                    |

package/dist/index.d.mts

@@ -22,7 +22,8 @@ interface ThemeColors {
 }
 /**
  * Generate a custom cascivo theme as CSS. Maps the three input colors onto the
- * semantic token layer; component tokens inherit automatically.
+ * semantic token layer via OKLCH relative color syntax + contrast-color(), each
+ * behind a static OKLCH fallback. Component tokens inherit automatically.
  */
 declare function generateThemeCss(colors: ThemeColors, name?: string): string;
 //#endregion

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/server.ts","../src/theme.ts","../src/scaffold.ts","../src/registry.ts","../src/grammar.ts","../src/prompt.ts","../src/index.ts"],"mappings":";;;KA0BK,OAAA,IAAW,GAAA,UAAa,IAAA,GAAO,WAAA,KAAgB,OAAA,CAAQ,QAAA;AAAA,UAE3C,aAAA;EACf,YAAA;EACA,OAAA;;EAEA,OAAA,GAAU,OAAO;AAAA;;iBAeH,YAAA,CAAa,OAAA,GAAS,aAAA,GAAqB,SAAS;;;UC/CnD,WAAA;;EAEf,OAAA;EDwBG;ECtBH,OAAA;;EAEA,MAAA;AAAA;;;;;iBAiBc,gBAAA,CAAiB,MAAA,EAAQ,WAAW,EAAE,IAAA;;;UCvBrC,eAAA;EACf,WAAA;EACA,UAAU;AAAA;;;;;iBAgCI,YAAA,CAAa,OAAwB,EAAf,eAAe;;;UC9BpC,YAAA;EACf,IAAA;EACA,IAAA;EACA,QAAA;EACA,OAAA;EACA,WAAA;AAAA;AAAA,UAGe,iBAAA;EACf,IAAA;EACA,WAAA;EACA,QAAA;EACA,MAAA;EACA,QAAA;EACA,KAAA;EACA,KAAA,EAAO,YAAY;EACnB,MAAA;EACA,aAAA;IAAiB,IAAA;IAAc,IAAA;IAAc,QAAA;EAAA;EAC7C,QAAA;IAAY,KAAA;IAAe,IAAA;IAAc,WAAA;EAAA;EACzC,YAAA;EACA,IAAA;AAAA;AAAA,UAGe,iBAAA;EACf,IAAA;EACA,IAAA;EACA,WAAA;EACA,QAAA;EACA,OAAA;EACA,KAAA;EACA,YAAA;EACA,IAAA;EACA,IAAA,EAAM,iBAAiB;AAAA;AAAA,UAGR,QAAA;EACf,OAAA;EACA,WAAA;EACA,UAAA,EAAY,iBAAiB;AAAA;AAAA,iBAwBf,YAAA,CAAa,IAAA,YAAgB,QAAQ;;iBAUrC,cAAA,CACd,QAAA,EAAU,QAAA,EACV,QAAA,WACA,IAAA,YACC,iBAAiB;;iBAQJ,YAAA,CAAa,QAAA,EAAU,QAAA,EAAU,IAAA,WAAe,iBAAiB;;iBAoGjE,gBAAA,CAAiB,QAAA,EAAU,QAAA,EAAU,KAAA,WAAgB,iBAAiB;;;UChLrE,WAAA;EACf,IAAA;EACA,QAAA;EJYU;EIVV,IAAA;EJUkC;EIRlC,IAAA;AAAA;AAAA,UAGe,gBAAA;EACf,IAAA;EACA,QAAA;EACA,KAAA,EAAO,WAAW;EAClB,QAAA;EACA,KAAA;AAAA;AAAA,UAGe,WAAA;EACf,UAAA,EAAY,gBAAgB;AAAA;;;;;;iBAQd,SAAA,CAAU,IAAY;AAAA,iBA8BtB,YAAA,CAAa,QAAA,EAAU,QAAA,EAAU,MAAA,cAAoB,WAAW;;AJpC7D;AAenB;;;;iBI4EgB,aAAA,CAAc,OAAoB,EAAX,WAAW;;;UChHjC,uBAAA;;EAEf,UAAU;AAAA;;;;;;iBAsCI,qBAAA,CACd,QAAA,EAAU,QAAA,EACV,OAAA,GAAS,uBAA4B;;;cChD1B,OAAA;;iBA0BS,IAAA,IAAQ,OAAO"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/server.ts","../src/theme.ts","../src/scaffold.ts","../src/registry.ts","../src/grammar.ts","../src/prompt.ts","../src/index.ts"],"mappings":";;;KA2BK,OAAA,IAAW,GAAA,UAAa,IAAA,GAAO,WAAA,KAAgB,OAAA,CAAQ,QAAA;AAAA,UAE3C,aAAA;EACf,YAAA;EACA,OAAA;;EAEA,OAAA,GAAU,OAAO;AAAA;;iBAeH,YAAA,CAAa,OAAA,GAAS,aAAA,GAAqB,SAAS;;;UChDnD,WAAA;;EAEf,OAAA;EDyBG;ECvBH,OAAA;;EAEA,MAAA;AAAA;;;;;AD2BiB;iBCmJH,gBAAA,CAAiB,MAAA,EAAQ,WAAW,EAAE,IAAA;;;UCpLrC,eAAA;EACf,WAAA;EACA,UAAU;AAAA;;;;;iBAgCI,YAAA,CAAa,OAAwB,EAAf,eAAe;;;UC9BpC,YAAA;EACf,IAAA;EACA,IAAA;EACA,QAAA;EACA,OAAA;EACA,WAAA;AAAA;AAAA,UAGe,iBAAA;EACf,IAAA;EACA,WAAA;EACA,QAAA;EACA,MAAA;EACA,QAAA;EACA,KAAA;EACA,KAAA,EAAO,YAAY;EACnB,MAAA;EACA,aAAA;IAAiB,IAAA;IAAc,IAAA;IAAc,QAAA;EAAA;EAC7C,QAAA;IAAY,KAAA;IAAe,IAAA;IAAc,WAAA;EAAA;EACzC,YAAA;EACA,IAAA;AAAA;AAAA,UAGe,iBAAA;EACf,IAAA;EACA,IAAA;EACA,WAAA;EACA,QAAA;EACA,OAAA;EACA,KAAA;EACA,YAAA;EACA,IAAA;EACA,IAAA,EAAM,iBAAiB;AAAA;AAAA,UAGR,QAAA;EACf,OAAA;EACA,WAAA;EACA,UAAA,EAAY,iBAAiB;AAAA;AAAA,iBAwBf,YAAA,CAAa,IAAA,YAAgB,QAAQ;;iBAUrC,cAAA,CACd,QAAA,EAAU,QAAA,EACV,QAAA,WACA,IAAA,YACC,iBAAiB;;iBAQJ,YAAA,CAAa,QAAA,EAAU,QAAA,EAAU,IAAA,WAAe,iBAAiB;;iBAoGjE,gBAAA,CAAiB,QAAA,EAAU,QAAA,EAAU,KAAA,WAAgB,iBAAiB;;;UChLrE,WAAA;EACf,IAAA;EACA,QAAA;EJaU;EIXV,IAAA;EJWkC;EITlC,IAAA;AAAA;AAAA,UAGe,gBAAA;EACf,IAAA;EACA,QAAA;EACA,KAAA,EAAO,WAAW;EAClB,QAAA;EACA,KAAA;AAAA;AAAA,UAGe,WAAA;EACf,UAAA,EAAY,gBAAgB;AAAA;;;;;;iBAQd,SAAA,CAAU,IAAY;AAAA,iBA8BtB,YAAA,CAAa,QAAA,EAAU,QAAA,EAAU,MAAA,cAAoB,WAAW;;AJnC7D;AAenB;;;;iBI2EgB,aAAA,CAAc,OAAoB,EAAX,WAAW;;;UChHjC,uBAAA;;EAEf,UAAU;AAAA;;;;;;iBAsCI,qBAAA,CACd,QAAA,EAAU,QAAA,EACV,OAAA,GAAS,uBAA4B;;;cChD1B,OAAA;;iBA0BS,IAAA,IAAQ,OAAO"}

package/dist/index.mjs

@@ -8,7 +8,7 @@ import { z } from "zod";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 //#region src/registry.ts
-const HERE$3 = dirname(fileURLToPath(import.meta.url));
+const HERE$4 = dirname(fileURLToPath(import.meta.url));
 /**
 * Resolve the registry.json location. Checks, in order: an explicit path, the
 * `CASCIVO_REGISTRY_PATH` env var, a copy bundled next to the built server
@@ -18,9 +18,9 @@ function resolveRegistryPath(explicit) {
 	const candidates = [
 		explicit,
 		process.env.CASCIVO_REGISTRY_PATH,
-		join(HERE$3, "registry.json"),
-		join(HERE$3, "..", "..", "..", "registry.json"),
-		join(HERE$3, "..", "..", "registry.json")
+		join(HERE$4, "registry.json"),
+		join(HERE$4, "..", "..", "..", "registry.json"),
+		join(HERE$4, "..", "..", "registry.json")
 	].filter((p) => typeof p === "string" && p.length > 0);
 	return candidates.find((p) => existsSync(p)) ?? candidates[candidates.length - 1] ?? "registry.json";
 }
@@ -111,64 +111,175 @@ function searchComponents(registry, query) {
 }
 //#endregion
 //#region src/theme.ts
-/** Darken a color by mixing in black (modern CSS, no preprocessor). */
-function darken(color, amount) {
-	return `color-mix(in oklab, ${color}, black ${amount}%)`;
+const NAMED = {
+	black: "#000000",
+	white: "#ffffff",
+	red: "#ff0000",
+	green: "#008000",
+	blue: "#0000ff",
+	gray: "#808080",
+	grey: "#808080",
+	silver: "#c0c0c0",
+	maroon: "#800000",
+	olive: "#808000",
+	lime: "#00ff00",
+	aqua: "#00ffff",
+	teal: "#008080",
+	navy: "#000080",
+	fuchsia: "#ff00ff",
+	purple: "#800080",
+	orange: "#ffa500",
+	yellow: "#ffff00"
+};
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+const round = (n, p) => {
+	const f = 10 ** p;
+	return Math.round(n * f) / f;
+};
+/** sRGB (0–1, gamma-encoded) → OKLCH. Ottosson's reference transform. */
+function srgbToOklch(r, g, b) {
+	const lin = (c) => c <= .04045 ? c / 12.92 : ((c + .055) / 1.055) ** 2.4;
+	const rl = lin(r);
+	const gl = lin(g);
+	const bl = lin(b);
+	const l_ = Math.cbrt(.4122214708 * rl + .5363325363 * gl + .0514459929 * bl);
+	const m_ = Math.cbrt(.2119034982 * rl + .6806995451 * gl + .1073969566 * bl);
+	const s_ = Math.cbrt(.0883024619 * rl + .2817188376 * gl + .6299787005 * bl);
+	const L = .2104542553 * l_ + .793617785 * m_ - .0040720468 * s_;
+	const a = 1.9779984951 * l_ - 2.428592205 * m_ + .4505937099 * s_;
+	const bb = .0259040371 * l_ + .7827717662 * m_ - .808675766 * s_;
+	const C = Math.hypot(a, bb);
+	let H = Math.atan2(bb, a) * 180 / Math.PI;
+	if (H < 0) H += 360;
+	return {
+		l: clamp(L, 0, 1),
+		c: Math.max(0, C),
+		h: H
+	};
+}
+function hexToOklch(hex) {
+	let h = hex.slice(1);
+	if (h.length === 3) h = h.split("").map((ch) => ch + ch).join("");
+	return srgbToOklch(parseInt(h.slice(0, 2), 16) / 255, parseInt(h.slice(2, 4), 16) / 255, parseInt(h.slice(4, 6), 16) / 255);
+}
+/** Parse a hex / rgb() / oklch() / named color into OKLCH. Throws on unknown input. */
+function parseToOklch(input) {
+	const raw = input.trim().toLowerCase();
+	const named = NAMED[raw];
+	if (named) return hexToOklch(named);
+	if (raw.startsWith("#")) return hexToOklch(raw);
+	const oklchM = /^oklch\(\s*([\d.]+%?)\s+([\d.]+)\s+([\d.]+)(?:\s*\/\s*([\d.]+%?))?\s*\)$/.exec(raw);
+	if (oklchM) {
+		const parsePct = (s) => s.endsWith("%") ? parseFloat(s) / 100 : parseFloat(s);
+		const o = {
+			l: clamp(parsePct(oklchM[1]), 0, 1),
+			c: parseFloat(oklchM[2]),
+			h: parseFloat(oklchM[3])
+		};
+		if (oklchM[4]) o.a = parsePct(oklchM[4]);
+		return o;
+	}
+	const rgbM = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/.exec(raw);
+	if (rgbM) return srgbToOklch(parseFloat(rgbM[1]) / 255, parseFloat(rgbM[2]) / 255, parseFloat(rgbM[3]) / 255);
+	throw new Error(`create_theme: cannot parse color "${input}" — use hex, rgb(), oklch(), or a named color`);
+}
+/** Serialize OKLCH to a canonical `oklch(L C H[ / a])` literal. */
+function fmt(o) {
+	const base = `oklch(${round(o.l, 3)} ${round(o.c, 3)} ${round(o.h, 1)}`;
+	return o.a !== void 0 ? `${base} / ${round(o.a, 3)})` : `${base})`;
+}
+/** Apply a step to an OKLCH color (lightness/chroma deltas, optional alpha). */
+function step(o, d) {
+	const next = {
+		l: clamp(o.l + (d.dl ?? 0), 0, 1),
+		c: Math.max(0, o.c * (d.dc ?? 1)),
+		h: o.h
+	};
+	if (d.a !== void 0) next.a = d.a;
+	return next;
+}
+/**
+* Emit a fallback-then-derived declaration pair: the static OKLCH literal first
+* (what every browser uses), then the relative-color form (progressive). Both
+* are computed from the same base + delta so they agree.
+*/
+function derive(prop, baseToken, base, d) {
+	return `    ${prop}: ${fmt(step(base, d))};\n    ${prop}: ${`oklch(from var(${baseToken}) ${d.dl ? `calc(l ${d.dl >= 0 ? "+" : "-"} ${Math.abs(d.dl)})` : "l"} ${d.dc !== void 0 && d.dc !== 1 ? `calc(c * ${d.dc})` : "c"} h${d.a !== void 0 ? ` / ${d.a}` : ""})`};\n`;
 }
-/** Lighten a color by mixing in white. */
-function lighten(color, amount) {
-	return `color-mix(in oklab, ${color}, white ${amount}%)`;
+/** A plain static OKLCH literal declaration (no derivation). */
+function lit(prop, o) {
+	return `    ${prop}: ${fmt(o)};\n`;
 }
 /**
+* Pick a WCAG-safe on-color (used as the static fallback for contrast-color()):
+* dark text on light surfaces, light text on dark ones.
+*/
+function onColor(base) {
+	return base.l > .6 ? {
+		l: .145,
+		c: .005,
+		h: base.h
+	} : {
+		l: 1,
+		c: 0,
+		h: 0
+	};
+}
+const DESTRUCTIVE = {
+	l: .577,
+	c: .215,
+	h: 27.3
+};
+const SUCCESS = {
+	l: .627,
+	c: .176,
+	h: 149.6
+};
+const WARNING = {
+	l: .769,
+	c: .166,
+	h: 70.7
+};
+/**
 * Generate a custom cascivo theme as CSS. Maps the three input colors onto the
-* semantic token layer; component tokens inherit automatically.
+* semantic token layer via OKLCH relative color syntax + contrast-color(), each
+* behind a static OKLCH fallback. Component tokens inherit automatically.
 */
 function generateThemeCss(colors, name = "custom") {
-	const { primary, neutral, accent } = colors;
+	const primary = parseToOklch(colors.primary);
+	const neutral = parseToOklch(colors.neutral);
+	const accent = parseToOklch(colors.accent);
+	const surface = (l, cMul = .15) => ({
+		l,
+		c: round(neutral.c * cMul, 3),
+		h: neutral.h
+	});
+	const onAccent = onColor(primary);
+	const onDestructive = onColor(DESTRUCTIVE);
 	return `/* cascivo — Generated theme: ${name} */
+/* Built like the first-party themes: OKLCH + relative color syntax + */
+/* contrast-color(), every progressive value behind a static fallback. */
 
 @layer cascivo.theme {
   [data-theme='${name}'] {
     color-scheme: light;
 
     /* ── Surface (derived from neutral) ───────────────── */
-    --cascivo-color-bg: ${lighten(neutral, 96)};
-    --cascivo-color-bg-subtle: ${lighten(neutral, 92)};
-    --cascivo-color-surface: ${lighten(neutral, 98)};
-    --cascivo-color-surface-raised: ${lighten(neutral, 94)};
-    --cascivo-color-surface-overlay: ${lighten(neutral, 98)};
-    --cascivo-color-border: ${lighten(neutral, 80)};
-    --cascivo-color-border-strong: ${lighten(neutral, 65)};
-
+${lit("--cascivo-color-bg", surface(.99))}${lit("--cascivo-color-bg-subtle", surface(.975))}${lit("--cascivo-color-surface", surface(.985))}${lit("--cascivo-color-surface-raised", surface(.97))}${lit("--cascivo-color-surface-overlay", surface(.99))}${lit("--cascivo-color-border", surface(.9, .25))}${lit("--cascivo-color-border-strong", surface(.8, .3))}
     /* ── Text (derived from neutral) ──────────────────── */
-    --cascivo-color-text: ${darken(neutral, 80)};
-    --cascivo-color-text-subtle: ${darken(neutral, 50)};
-    --cascivo-color-text-muted: ${lighten(neutral, 30)};
-    --cascivo-color-text-on-accent: #ffffff;
-    --cascivo-color-text-on-destructive: #ffffff;
-
-    /* ── Accent / primary interactive ─────────────────── */
-    --cascivo-color-accent: ${primary};
-    --cascivo-color-accent-hover: ${darken(primary, 12)};
-    --cascivo-color-accent-active: ${darken(primary, 24)};
-    --cascivo-color-accent-subtle: ${lighten(primary, 88)};
-    --cascivo-color-accent-muted: ${lighten(primary, 76)};
+${lit("--cascivo-color-text", surface(.22, .4))}${lit("--cascivo-color-text-subtle", surface(.45, .35))}${lit("--cascivo-color-text-muted", surface(.6, .3))}
+    /* on-color: static fallback then auto-contrast (WCAG) */
+    --cascivo-color-text-on-accent: ${fmt(onAccent)};
+    --cascivo-color-text-on-accent: contrast-color(var(--cascivo-color-accent));
+    --cascivo-color-text-on-destructive: ${fmt(onDestructive)};
+    --cascivo-color-text-on-destructive: contrast-color(var(--cascivo-color-destructive));
 
+    /* ── Accent / primary interactive (derived from one base) ── */
+${lit("--cascivo-color-accent", primary)}${derive("--cascivo-color-accent-hover", "--cascivo-color-accent", primary, { dl: -.077 })}${derive("--cascivo-color-accent-active", "--cascivo-color-accent", primary, { dl: -.154 })}${derive("--cascivo-color-accent-subtle", "--cascivo-color-accent", primary, { a: .1 })}${derive("--cascivo-color-accent-muted", "--cascivo-color-accent", primary, { a: .2 })}
     /* ── Secondary accent (info / focus) ──────────────── */
-    --cascivo-color-info: ${accent};
-    --cascivo-color-info-subtle: ${lighten(accent, 88)};
-    --cascivo-color-focus-ring: ${accent};
-    --cascivo-focus-ring: 0 0 0 3px ${lighten(accent, 20)};
-
-    /* ── Status ───────────────────────────────────────── */
-    --cascivo-color-destructive: #dc2626;
-    --cascivo-color-destructive-hover: ${darken("#dc2626", 12)};
-    --cascivo-color-destructive-subtle: ${lighten("#dc2626", 88)};
-    --cascivo-color-success: #16a34a;
-    --cascivo-color-success-subtle: ${lighten("#16a34a", 88)};
-    --cascivo-color-warning: #f59e0b;
-    --cascivo-color-warning-subtle: ${lighten("#f59e0b", 88)};
-  }
+${lit("--cascivo-color-info", accent)}${derive("--cascivo-color-info-subtle", "--cascivo-color-info", accent, { a: .1 })}${lit("--cascivo-color-focus-ring", accent)}
+    /* ── Status (in-system OKLCH; no hex) ─────────────── */
+${lit("--cascivo-color-destructive", DESTRUCTIVE)}${derive("--cascivo-color-destructive-hover", "--cascivo-color-destructive", DESTRUCTIVE, { dl: -.077 })}${derive("--cascivo-color-destructive-subtle", "--cascivo-color-destructive", DESTRUCTIVE, { a: .1 })}${lit("--cascivo-color-success", SUCCESS)}${derive("--cascivo-color-success-subtle", "--cascivo-color-success", SUCCESS, { a: .1 })}${lit("--cascivo-color-warning", WARNING)}${derive("--cascivo-color-warning-subtle", "--cascivo-color-warning", WARNING, { a: .1 })}  }
 }
 `;
 }
@@ -496,10 +607,10 @@ function buildGenerationPrompt(registry, options = {}) {
 }
 //#endregion
 //#region src/tokens.ts
-const HERE$2 = dirname(fileURLToPath(import.meta.url));
+const HERE$3 = dirname(fileURLToPath(import.meta.url));
 const CATALOG_BASE_URL = "https://cascivo.com";
 async function loadTokenCatalog(fetchFn) {
-	const localPaths = [join(HERE$2, "..", "..", "..", "apps", "docs", "public", "tokens.catalog.json"), join(HERE$2, "tokens.catalog.json")];
+	const localPaths = [join(HERE$3, "..", "..", "..", "apps", "site", "public", "tokens.catalog.json"), join(HERE$3, "tokens.catalog.json")];
 	for (const p of localPaths) if (existsSync(p)) return JSON.parse(readFileSync(p, "utf8"));
 	const res = await (fetchFn ?? fetch)(`${CATALOG_BASE_URL}/tokens.catalog.json`);
 	if (!res.ok) throw new Error(`Failed to fetch token catalog: ${res.status}`);
@@ -507,10 +618,10 @@ async function loadTokenCatalog(fetchFn) {
 }
 //#endregion
 //#region src/variants.ts
-const HERE$1 = dirname(fileURLToPath(import.meta.url));
+const HERE$2 = dirname(fileURLToPath(import.meta.url));
 const BASE_URL = "https://cascivo.com";
 async function loadVariantMatrix(fetchFn) {
-	const localPaths = [join(HERE$1, "..", "..", "..", "apps", "docs", "public", "tokens.variants.json"), join(HERE$1, "tokens.variants.json")];
+	const localPaths = [join(HERE$2, "..", "..", "..", "apps", "site", "public", "tokens.variants.json"), join(HERE$2, "tokens.variants.json")];
 	for (const p of localPaths) if (existsSync(p)) return JSON.parse(readFileSync(p, "utf8"));
 	const res = await (fetchFn ?? fetch)(`${BASE_URL}/tokens.variants.json`);
 	if (!res.ok) throw new Error(`Failed to fetch variant matrix: ${res.status}`);
@@ -647,6 +758,27 @@ function checkTokens(css, tokenNames) {
 	}
 	return violations;
 }
+/** Flag `var(--cascivo-…)` references that use an alias where a canonical token exists. */
+function checkAliasTokens(css, aliasMap) {
+	if (aliasMap.size === 0) return [];
+	const violations = [];
+	const re = /var\(\s*(--cascivo-[\w-]+)/g;
+	let m;
+	const seen = /* @__PURE__ */ new Set();
+	while ((m = re.exec(css)) !== null) {
+		const token = m[1];
+		const canonical = aliasMap.get(token);
+		if (!canonical || seen.has(token)) continue;
+		seen.add(token);
+		violations.push({
+			rule: "alias-token-used",
+			severity: "warning",
+			line: lineOf(css, m.index),
+			detail: `"${token}" is an alias — prefer the canonical "${canonical}"`
+		});
+	}
+	return violations;
+}
 /** Run all structural invariants over a candidate component's source. */
 function validateComponentSource(input, options = {}) {
 	const violations = [];
@@ -655,6 +787,7 @@ function validateComponentSource(input, options = {}) {
 		violations.push(...checkBreakpoints(input.css));
 		violations.push(...checkFallbacks(input.css));
 		if (options.tokenNames) violations.push(...checkTokens(input.css, options.tokenNames));
+		if (options.aliasMap) violations.push(...checkAliasTokens(input.css, options.aliasMap));
 	}
 	violations.sort((a, b) => a.line - b.line);
 	return {
@@ -665,10 +798,10 @@ function validateComponentSource(input, options = {}) {
 }
 //#endregion
 //#region src/context.ts
-const HERE = dirname(fileURLToPath(import.meta.url));
+const HERE$1 = dirname(fileURLToPath(import.meta.url));
 const CONTEXT_BASE_URL = "https://cascivo.com";
 async function loadContext(fetchFn) {
-	const localPaths = [join(HERE, "..", "..", "..", "apps", "docs", "public", "context.json"), join(HERE, "context.json")];
+	const localPaths = [join(HERE$1, "..", "..", "..", "apps", "site", "public", "context.json"), join(HERE$1, "context.json")];
 	for (const p of localPaths) if (existsSync(p)) return JSON.parse(readFileSync(p, "utf8"));
 	const res = await (fetchFn ?? fetch)(`${CONTEXT_BASE_URL}/context.json`);
 	if (!res.ok) throw new Error(`Failed to fetch context bundle: ${res.status}`);
@@ -676,7 +809,7 @@ async function loadContext(fetchFn) {
 }
 async function loadComponentMarkdown(name, fetchFn) {
 	const slug = name.toLowerCase().replace(/\s+/g, "-");
-	const localPaths = [join(HERE, "..", "..", "..", "apps", "docs", "public", "context", `${slug}.md`), join(HERE, "context", `${slug}.md`)];
+	const localPaths = [join(HERE$1, "..", "..", "..", "apps", "site", "public", "context", `${slug}.md`), join(HERE$1, "context", `${slug}.md`)];
 	for (const p of localPaths) if (existsSync(p)) return readFileSync(p, "utf8");
 	const url = `${CONTEXT_BASE_URL}/context/${slug}.md`;
 	const fn = fetchFn ?? fetch;
@@ -739,6 +872,57 @@ function selectComponent(need, components) {
 	})).filter((r) => r.score >= 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, 5);
 }
 //#endregion
+//#region src/templates.ts
+const HERE = dirname(fileURLToPath(import.meta.url));
+const EMPTY = {
+	generatedAt: "",
+	templates: [],
+	facets: {
+		categories: [],
+		frameworks: [],
+		tags: []
+	}
+};
+/**
+* Resolve the marketplace catalog location. Checks, in order: an explicit path,
+* the `CASCIVO_MARKETPLACE_PATH` env var, a copy bundled next to the built
+* server, and the in-repo `apps/site/public/marketplace.json` (dev).
+*/
+function resolveCatalogPath(explicit) {
+	const candidates = [
+		explicit,
+		process.env.CASCIVO_MARKETPLACE_PATH,
+		join(HERE, "marketplace.json"),
+		join(HERE, "..", "..", "..", "apps", "site", "public", "marketplace.json"),
+		join(HERE, "..", "..", "apps", "site", "public", "marketplace.json")
+	].filter((p) => typeof p === "string" && p.length > 0);
+	return candidates.find((p) => existsSync(p)) ?? candidates[candidates.length - 1] ?? "";
+}
+/** Load the marketplace catalog, returning an empty catalog if none is found. */
+function loadCatalog(explicit) {
+	const path = resolveCatalogPath(explicit);
+	if (!path || !existsSync(path)) return EMPTY;
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return EMPTY;
+	}
+}
+/** Filter the catalog's templates. Pure. */
+function listTemplates(catalog, filter = {}) {
+	return catalog.templates.filter((t) => {
+		if (filter.category && t.category !== filter.category) return false;
+		if (filter.framework && t.framework !== filter.framework) return false;
+		if (filter.verifiedOnly && !t.verified) return false;
+		if (filter.tag && !t.tags.includes(filter.tag)) return false;
+		return true;
+	});
+}
+/** Find one template by name or installSpec. Pure. */
+function getTemplate(catalog, name) {
+	return catalog.templates.find((t) => t.name === name || t.installSpec === name);
+}
+//#endregion
 //#region src/server.ts
 const json = (value) => ({ content: [{
 	type: "text",
@@ -860,6 +1044,84 @@ function createServer(options = {}) {
 		if (result.status !== 0) return error(result.stderr || result.error?.message || `Failed to add "${name}".`);
 		return text(result.stdout || `Added ${name}.`);
 	});
+	server.registerTool("list_templates", {
+		title: "List templates",
+		description: "List marketplace templates (whole-page compositions) from the static catalog, optionally filtered by category, tag, framework, or verified status.",
+		inputSchema: {
+			category: z.string().optional().describe("Filter by category, e.g. \"dashboard\""),
+			tag: z.string().optional().describe("Filter by tag"),
+			framework: z.enum(["react-vite", "react-next"]).optional().describe("Filter by target framework"),
+			verifiedOnly: z.boolean().optional().describe("Only verified templates")
+		}
+	}, ({ category, tag, framework, verifiedOnly }) => {
+		const catalog = loadCatalog();
+		const filter = {};
+		if (category) filter.category = category;
+		if (tag) filter.tag = tag;
+		if (framework) filter.framework = framework;
+		if (verifiedOnly) filter.verifiedOnly = verifiedOnly;
+		return json(listTemplates(catalog, filter));
+	});
+	server.registerTool("get_template", {
+		title: "Get template",
+		description: "Get one marketplace template by name or install spec — its components, install command, demo link, and screenshots.",
+		inputSchema: { name: z.string().describe("Template name or install spec, e.g. \"@cascivo/dashboard\"") }
+	}, ({ name }) => {
+		const tpl = getTemplate(loadCatalog(), name);
+		if (!tpl) return error(`Template "${name}" not found in the marketplace catalog.`);
+		return json(tpl);
+	});
+	server.registerTool("add_template", {
+		title: "Add template",
+		description: "Install a marketplace template (its components + page/fixture files) into the current project by running the cascade CLI.",
+		inputSchema: {
+			name: z.string().describe("Template name or install spec, e.g. \"@cascivo/dashboard\""),
+			cwd: z.string().optional().describe("Project directory (default: current directory)")
+		}
+	}, ({ name, cwd }) => {
+		const spec = getTemplate(loadCatalog(), name)?.installSpec ?? name;
+		const result = spawnSync("npx", [
+			"-y",
+			"cascivo",
+			"add",
+			spec
+		], {
+			encoding: "utf8",
+			...cwd ? { cwd } : {}
+		});
+		if (result.status !== 0) return error(result.stderr || result.error?.message || `Failed to add template "${spec}".`);
+		return text(result.stdout || `Added template ${spec}.`);
+	});
+	server.registerTool("create_app", {
+		title: "Create app",
+		description: "Scaffold a complete, ready-to-run cascivo app (Vite + React + TypeScript) wired with the app shell, side navigation, header, and a theme — one page per nav section, with signal-driven section switching. Runs `cascivo create` as a child process, writing the project into a new <name> directory.",
+		inputSchema: {
+			name: z.string().describe("Project name and directory, e.g. \"my-app\""),
+			theme: z.enum([
+				"light",
+				"dark",
+				"warm"
+			]).optional().describe("Theme to wire in (default: light)"),
+			sections: z.array(z.string()).optional().describe("Side-nav section labels; one page is generated per section (default: Dashboard, Reports, Settings)"),
+			cwd: z.string().optional().describe("Directory to create the app in (default: current directory)")
+		}
+	}, ({ name, theme, sections, cwd }) => {
+		const args = [
+			"-y",
+			"cascivo",
+			"create",
+			name,
+			"--yes"
+		];
+		if (theme) args.push("--theme", theme);
+		if (sections && sections.length > 0) args.push("--sections", sections.join(", "));
+		const result = spawnSync("npx", args, {
+			encoding: "utf8",
+			...cwd ? { cwd } : {}
+		});
+		if (result.status !== 0) return error(result.stderr || result.error?.message || `Failed to create "${name}".`);
+		return text(result.stdout || `Created ${name}.`);
+	});
 	server.registerTool("create_theme", {
 		title: "Create theme",
 		description: "Generate a cascade theme CSS file from three colors.",
@@ -990,18 +1252,20 @@ export function Diagram() {
 	});
 	server.registerTool("get_tokens", {
 		title: "Get tokens",
-		description: "Get the cascade token catalog (closed set). Agents must select from this catalog rather than hard-coding values.",
+		description: "Get the cascade token catalog (closed set). Agents must select from this catalog rather than hard-coding values. Returns the CANONICAL token set by default — exactly one name per purpose. Pass includeAliases: true to also list backwards-compat aliases, each tagged with its canonical name.",
 		inputSchema: {
 			group: z.string().optional().describe("Filter by token group, e.g. \"color\", \"space\", \"radius\""),
 			layer: z.enum([
 				"primitive",
 				"semantic",
 				"component"
-			]).optional().describe("Filter by layer")
+			]).optional().describe("Filter by layer"),
+			includeAliases: z.boolean().optional().describe("Include backwards-compat alias tokens (e.g. --cascivo-color-bg → --cascivo-color-background). Off by default so agents see one correct token per purpose.")
 		}
-	}, async ({ group, layer }) => {
+	}, async ({ group, layer, includeAliases }) => {
 		try {
 			let tokens = (await loadTokenCatalog(fetchFn)).tokens;
+			if (!includeAliases) tokens = tokens.filter((t) => !t.aliasOf);
 			if (group) tokens = tokens.filter((t) => t.group === group);
 			if (layer) tokens = tokens.filter((t) => t.layer === layer);
 			return json({
@@ -1053,15 +1317,20 @@ export function Diagram() {
 		}
 	}, async ({ tsx, css, name }) => {
 		let tokenNames;
+		let aliasMap;
 		try {
 			const catalog = await loadTokenCatalog(fetchFn);
 			tokenNames = new Set(catalog.tokens.map((t) => t.name));
+			aliasMap = new Map(catalog.tokens.filter((t) => t.aliasOf).map((t) => [t.name, t.aliasOf]));
 		} catch {}
 		return json(validateComponentSource({
 			...tsx ? { tsx } : {},
 			...css ? { css } : {},
 			...name ? { name } : {}
-		}, tokenNames ? { tokenNames } : {}));
+		}, {
+			...tokenNames ? { tokenNames } : {},
+			...aliasMap && aliasMap.size > 0 ? { aliasMap } : {}
+		}));
 	});
 	server.registerTool("get_context", {
 		title: "Get context",