camox 0.36.2 → 0.38.0

package/dist/features/vite/definitionsSync.js

@@ -9,17 +9,17 @@ const SYNC_DEBOUNCE_DELAY_MS = 100;
 * This is the core sync logic, independent of ViteDevServer.
 */
 function throwIfSyncAuthError(error) {
-	if (error instanceof Error && error.name === "ORPCError" && error.message.toLowerCase().includes("unauthorized")) throw new Error("[camox] Definition sync failed: invalid syncSecret.");
+	if (error instanceof Error && error.name === "ORPCError" && error.message.toLowerCase().includes("unauthorized")) throw new Error("[camox] Definition sync failed: invalid or missing credentials.");
 }
 function isNotFoundError(error) {
 	return error instanceof Error && error.name === "ORPCError" && error.message.toLowerCase().includes("not found");
 }
 function throwUnknownEnvironmentError(environmentName) {
-	throw new Error(`[camox] Environment "${environmentName}" does not exist. CAMOX_ENV must be "production" or a dev environment previously created by running the dev server while authenticated. Run \`npx camox login\` if needed.`);
+	throw new Error(`[camox] Environment "${environmentName}" does not exist. Run the dev server while authenticated to create your personal environment first.`);
 }
 async function syncDefinitionsToApi(options) {
-	const { camoxApp, projectSlug, apiUrl, syncSecret, environmentName, autoCreate, logger } = options;
-	const client = createServerApiClient(apiUrl, environmentName);
+	const { camoxApp, projectSlug, apiUrl, environmentName, autoCreate, authToken, deployToken, logger } = options;
+	const client = createServerApiClient(apiUrl, environmentName, authToken);
 	const blocks = camoxApp.getBlocks();
 	const layoutDefinitions = camoxApp.getSerializableLayoutDefinitions();
 	const typesUsedInLayouts = /* @__PURE__ */ new Set();
@@ -40,7 +40,7 @@ async function syncDefinitionsToApi(options) {
 	try {
 		const result = await client.blockDefinitions.sync({
 			projectSlug,
-			syncSecret,
+			deployToken,
 			autoCreate,
 			definitions
 		});
@@ -64,7 +64,7 @@ async function syncDefinitionsToApi(options) {
 		try {
 			layoutSyncResults = await client.layouts.sync({
 				projectSlug,
-				syncSecret,
+				deployToken,
 				autoCreate,
 				layouts: layoutDefinitions
 			});
@@ -99,7 +99,7 @@ async function syncDefinitionsToApi(options) {
 	if (initialPage) try {
 		const result = await client.projects.initializeContent({
 			projectSlug,
-			syncSecret,
+			deployToken,
 			layoutId: initialPage.layoutId,
 			blocks: initialPage.blocks
 		});
@@ -140,10 +140,10 @@ async function ssrLoadModule(server, modulePath) {
 	}
 }
 async function syncDefinitions(server, options) {
-	const { projectSlug, syncSecret, apiUrl, environmentName, autoCreate } = options;
+	const { projectSlug, apiUrl, environmentName, autoCreate, authToken, deployToken } = options;
 	const blocksDirs = [path.resolve(server.config.root, "src/blocks"), path.resolve(server.config.root, "src/camox/blocks")];
 	const layoutsDirs = [path.resolve(server.config.root, "src/layouts"), path.resolve(server.config.root, "src/camox/layouts")];
-	const client = createServerApiClient(apiUrl, environmentName);
+	const client = createServerApiClient(apiUrl, environmentName, authToken);
 	async function performInitialSync() {
 		const appModule = server.moduleGraph.getModuleById(CAMOX_APP_PATH);
 		if (appModule) server.moduleGraph.invalidateModule(appModule);
@@ -156,9 +156,10 @@ async function syncDefinitions(server, options) {
 			camoxApp: camoxModule.camoxApp,
 			projectSlug,
 			apiUrl,
-			syncSecret,
 			environmentName,
 			autoCreate,
+			authToken,
+			deployToken,
 			logger: server.config.logger
 		});
 	}
@@ -177,7 +178,7 @@ async function syncDefinitions(server, options) {
 		try {
 			result = await client.blockDefinitions.upsert({
 				projectSlug,
-				syncSecret,
+				deployToken,
 				blockId: block._internal.id,
 				title: block._internal.title,
 				description: block._internal.description,
@@ -199,7 +200,7 @@ async function syncDefinitions(server, options) {
 		try {
 			result = await client.blockDefinitions.delete({
 				projectSlug,
-				syncSecret,
+				deployToken,
 				blockId
 			});
 		} catch (error) {

package/dist/features/vite/devAuthentication.js

@@ -0,0 +1,188 @@
+import { verifyOneTimeToken, writeAuthTokenForUrl } from "@camox/cli/auth";
+import { randomBytes } from "node:crypto";
+
+//#region src/features/vite/devAuthentication.ts
+const CALLBACK_PATH = "/__camox/auth/callback";
+const READY_PATH = "/__camox/auth/ready";
+const AUTH_REQUEST_TTL_MS = 600 * 1e3;
+function normalizeUrl(url) {
+	return url.replace(/\/+$/, "");
+}
+function isLoopbackHostname(hostname) {
+	const normalizedHostname = hostname.toLowerCase();
+	if (normalizedHostname === "localhost" || normalizedHostname.endsWith(".localhost")) return true;
+	if (normalizedHostname === "[::1]" || normalizedHostname === "::1") return true;
+	return /^127(?:\.\d{1,3}){3}$/.test(normalizedHostname);
+}
+function getRequestOrigin(req, server) {
+	const host = req.headers.host;
+	if (!host) return null;
+	try {
+		const protocol = server.config.server.https ? "https" : "http";
+		const origin = new URL(`${protocol}://${host}`);
+		if (!isLoopbackHostname(origin.hostname)) return null;
+		return origin.origin;
+	} catch {
+		return null;
+	}
+}
+function getReturnPath(req, origin) {
+	const url = new URL(req.url ?? "/", origin);
+	return `${url.pathname}${url.search}`;
+}
+function redirect(res, location) {
+	res.writeHead(302, {
+		"Cache-Control": "no-store",
+		Location: location
+	});
+	res.end();
+}
+function sendUnavailable(res) {
+	res.writeHead(503, {
+		"Cache-Control": "no-store",
+		"Content-Type": "application/json; charset=utf-8",
+		"Retry-After": "1"
+	});
+	res.end(JSON.stringify({ error: "Camox authentication required" }));
+}
+function sendRestartingPage(res, returnPath) {
+	const serializedReturnPath = JSON.stringify(returnPath).replaceAll("<", "\\u003c");
+	res.writeHead(200, {
+		"Cache-Control": "no-store",
+		"Content-Type": "text/html; charset=utf-8"
+	});
+	res.end(`<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Connecting to Camox…</title>
+    <style>
+      :root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
+      body { align-items: center; background: #09090b; color: #fafafa; display: flex; justify-content: center; margin: 0; min-height: 100vh; }
+      main { align-items: center; display: flex; flex-direction: column; gap: 16px; text-align: center; }
+      .spinner { animation: spin 800ms linear infinite; border: 2px solid #3f3f46; border-radius: 999px; border-top-color: #fafafa; height: 24px; width: 24px; }
+      p { color: #a1a1aa; margin: 0; }
+      @keyframes spin { to { transform: rotate(360deg); } }
+    </style>
+  </head>
+  <body>
+    <main><div class="spinner"></div><p>Starting your Camox site…</p></main>
+    <script>
+      const returnPath = ${serializedReturnPath};
+      async function waitUntilReady() {
+        try {
+          const response = await fetch("${READY_PATH}", { cache: "no-store" });
+          if (response.ok) {
+            window.location.replace(returnPath);
+            return;
+          }
+        } catch {}
+        window.setTimeout(waitUntilReady, 250);
+      }
+      window.setTimeout(waitUntilReady, 250);
+    <\/script>
+  </body>
+</html>`);
+}
+function installDevAuthenticationMiddleware(server, options) {
+	const pendingAuthentications = /* @__PURE__ */ new Map();
+	let loggedAuthorizationUrl = false;
+	server.middlewares.use((req, res, next) => {
+		const requestUrl = new URL(req.url ?? "/", "http://localhost");
+		if (requestUrl.pathname === READY_PATH) {
+			if (!options.isAuthenticated) {
+				sendUnavailable(res);
+				return;
+			}
+			res.writeHead(204, { "Cache-Control": "no-store" });
+			res.end();
+			return;
+		}
+		if (options.isAuthenticated) {
+			next();
+			return;
+		}
+		if (requestUrl.pathname === CALLBACK_PATH) {
+			if (req.method !== "GET") {
+				res.writeHead(405, { Allow: "GET" });
+				res.end();
+				return;
+			}
+			handleAuthenticationCallback(req, res, server, options, pendingAuthentications);
+			return;
+		}
+		const acceptsHtml = req.headers.accept?.includes("text/html") ?? false;
+		if (req.method !== "GET" || !acceptsHtml) {
+			sendUnavailable(res);
+			return;
+		}
+		const origin = getRequestOrigin(req, server);
+		if (!origin) {
+			res.writeHead(400, {
+				"Cache-Control": "no-store",
+				"Content-Type": "text/plain; charset=utf-8"
+			});
+			res.end("Open this Camox development server through localhost to authenticate.");
+			return;
+		}
+		const now = Date.now();
+		for (const [state, pending] of pendingAuthentications) if (pending.expiresAt < now) pendingAuthentications.delete(state);
+		const state = randomBytes(32).toString("hex");
+		const callbackUrl = new URL(CALLBACK_PATH, origin);
+		callbackUrl.searchParams.set("state", state);
+		pendingAuthentications.set(state, {
+			callbackUrl: callbackUrl.toString(),
+			expiresAt: now + AUTH_REQUEST_TTL_MS,
+			returnPath: getReturnPath(req, origin)
+		});
+		const authorizationUrl = new URL("/dev-authorize", `${normalizeUrl(options.authenticationUrl)}/`);
+		authorizationUrl.searchParams.set("callback", callbackUrl.toString());
+		if (!loggedAuthorizationUrl) {
+			server.config.logger.info(`Camox authentication required: ${authorizationUrl}`, { timestamp: true });
+			loggedAuthorizationUrl = true;
+		}
+		redirect(res, authorizationUrl.toString());
+	});
+	const authenticationLayer = server.middlewares.stack.at(-1);
+	const nitroMiddlewareIndex = server.middlewares.stack.findIndex((layer) => typeof layer.handle === "function" && layer.handle.name === "nitroDevMiddlewarePre");
+	if (authenticationLayer && nitroMiddlewareIndex >= 0) {
+		server.middlewares.stack.pop();
+		server.middlewares.stack.splice(nitroMiddlewareIndex, 0, authenticationLayer);
+	}
+}
+async function handleAuthenticationCallback(req, res, server, options, pendingAuthentications) {
+	const requestUrl = new URL(req.url ?? "/", "http://localhost");
+	const state = requestUrl.searchParams.get("state");
+	const ott = requestUrl.searchParams.get("ott");
+	const pending = state ? pendingAuthentications.get(state) : void 0;
+	if (!state || !ott || !pending || pending.expiresAt < Date.now()) {
+		if (state) pendingAuthentications.delete(state);
+		res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+		res.end("This Camox authentication request is invalid or has expired. Reload the local site.");
+		return;
+	}
+	try {
+		const authToken = await verifyOneTimeToken(options.apiUrl, ott);
+		writeAuthTokenForUrl(options.authenticationUrl, authToken);
+		pendingAuthentications.delete(state);
+		server.config.logger.info(`Authenticated with Camox as ${authToken.email || authToken.name}.`, { timestamp: true });
+		res.once("finish", () => {
+			setTimeout(() => {
+				server.restart().catch((error) => {
+					server.config.logger.error(`Unable to restart the Camox development server: ${String(error)}`, { timestamp: true });
+				});
+			}, 25);
+		});
+		sendRestartingPage(res, pending.returnPath);
+	} catch (error) {
+		server.config.logger.error(`Camox authentication failed: ${String(error)}`, { timestamp: true });
+		const authorizationUrl = new URL("/dev-authorize", `${normalizeUrl(options.authenticationUrl)}/`);
+		authorizationUrl.searchParams.set("callback", pending.callbackUrl);
+		authorizationUrl.searchParams.set("error", "callback_failed");
+		redirect(res, authorizationUrl.toString());
+	}
+}
+
+//#endregion
+export { installDevAuthenticationMiddleware };

package/dist/features/vite/runtimeDev.js

@@ -50,7 +50,7 @@ function resolveSdkAlias(id, importer) {
 	].find((candidate) => existsSync(candidate));
 }
 function resolveCamoxSourceImport(id) {
-	return {
+	const sourceImport = {
 		"camox/createApp": resolve(sdkRoot, "src/core/createApp.ts"),
 		"camox/createBlock": resolve(sdkRoot, "src/core/createBlock.tsx"),
 		"camox/createLayout": resolve(sdkRoot, "src/core/createLayout.tsx"),
@@ -64,6 +64,8 @@ function resolveCamoxSourceImport(id) {
 		"camox/_internal/studioServer": resolve(sdkRoot, "src/features/runtime/studioServer.tsx"),
 		"camox/_internal/runtime": resolve(sdkRoot, "src/features/runtime/runtime.ts")
 	}[id];
+	if (!sourceImport || !existsSync(sourceImport)) return;
+	return sourceImport;
 }
 function generateVirtualCamoxApp() {
 	return `import { createApp } from "camox/createApp";

package/dist/features/vite/vite.d.ts

@@ -6,6 +6,7 @@ interface CamoxNitro {
     hook: (name: "compiled", callback: (nitro: CamoxNitro) => void) => void;
   };
   options: {
+    noExternals?: boolean | (string | RegExp)[];
     output: {
       publicDir: string;
       serverDir: string;
@@ -22,15 +23,13 @@ type CamoxVitePlugin = Plugin & {
 interface CamoxPluginOptions {
   /** Stable, human-readable slug identifying this project (e.g. "prestigious-impala-84") */
   projectSlug: string;
-  /** Secret used to authenticate definition sync requests with the API */
-  syncSecret: string;
   /** Disable PostHog telemetry collection (default: false) */
   disableTelemetry?: boolean;
   /** Internal options (intended for Camox contributors in development, not for public use) */
   _internal?: {
     /** URL of the Camox API backend, used for data fetching */apiUrl?: string; /** URL of the Camox authentication backend (default: https://app.camox.dev) */
     authenticationUrl?: string; /** Show Tanstack query devtools (default: false) */
-    enableTanstackDevtools?: boolean; /** Disable automatic code generation (route files, app file, skill files) (default: false) */
+    enableTanstackDevtools?: boolean; /** Disable automatic code generation (route files and app file) (default: false) */
     disableCodeGen?: boolean; /** Mount the Camox-owned dev runtime at this base path. Use "/" for root mode. */
     runtimeBasePath?: string;
   };

package/dist/features/vite/vite.js

@@ -1,15 +1,14 @@
 import { generateAppFile, watchAppFile } from "./appGeneration.js";
 import { watchNewBlockFiles } from "./blockBoilerplate.js";
+import { installDevAuthenticationMiddleware } from "./devAuthentication.js";
 import { syncDefinitions, syncDefinitionsToApi } from "./definitionsSync.js";
 import { cleanupGeneratedRouteFiles } from "./routeGeneration.js";
 import { installRuntimeNitroRoutes, loadRuntimeDevModule, resolveRuntimeDevId } from "./runtimeDev.js";
-import { generateSkillFiles, watchSkillFiles } from "./skillGeneration.js";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { readAuthTokenForUrl } from "@camox/cli/auth";
 import { createServer } from "vite-plus";
-import { z } from "zod";
 
 //#region src/features/vite/vite.ts
 const sdkRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
@@ -24,22 +23,6 @@ const RESOLVED_VIRTUAL_STUDIO_CLIENT_URL = "\0virtual:camox/studio-client-url";
 const PRODUCTION_API_URL = "https://api.camox.dev";
 /** Authentication URL to use for Camox authentication (production Camox Dashboard) */
 const DEFAULT_AUTHENTICATION_URL = "https://app.camox.dev";
-const authTokenSchema = z.object({
-	token: z.string(),
-	name: z.string(),
-	email: z.string()
-});
-const authFileSchema = z.record(z.string(), authTokenSchema);
-function readAuthEmail(authenticationUrl) {
-	const authFile = join(homedir(), ".camox", "auth.json");
-	const key = authenticationUrl.replace(/\/+$/, "");
-	try {
-		const raw = JSON.parse(readFileSync(authFile, "utf-8"));
-		return authFileSchema.parse(raw)[key]?.email ?? null;
-	} catch {
-		return null;
-	}
-}
 /**
 * Drop a sidecar at `<root>/node_modules/.camox/runtime.json` so the `camox`
 * CLI can pick up the same projectSlug / apiUrl / authenticationUrl the
@@ -54,18 +37,6 @@ function writeRuntimeSidecar(root, data) {
 	mkdirSync(dir, { recursive: true });
 	writeFileSync(join(dir, "runtime.json"), `${JSON.stringify(data, null, 2)}\n`);
 }
-function resolveEnvironmentName(command, authenticationUrl) {
-	if (command === "serve") {
-		const email = readAuthEmail(authenticationUrl);
-		if (!email) throw new Error("Camox: not authenticated. Run `npx camox login` to create your personal dev environment.");
-		return `dev:${email}`;
-	}
-	const envFromProcess = process.env.CAMOX_ENV;
-	if (envFromProcess) return envFromProcess;
-	const email = readAuthEmail(authenticationUrl);
-	const suggestion = email ? `  CAMOX_ENV=dev:${email}    (your personal dev environment)\n  CAMOX_ENV=production     (release build)` : `  CAMOX_ENV=production     (release build)\n\nIf you want to build against a dev environment, run \`npx camox login\` first.`;
-	throw new Error(`Camox: CAMOX_ENV is required on build. Set it to one of:\n${suggestion}`);
-}
 function camox(options) {
 	const apiUrl = options._internal?.apiUrl ?? PRODUCTION_API_URL;
 	const authenticationUrl = options._internal?.authenticationUrl ?? DEFAULT_AUTHENTICATION_URL;
@@ -73,8 +44,10 @@ function camox(options) {
 	const disableCodeGen = options._internal?.disableCodeGen ?? false;
 	const runtimeBasePath = options._internal?.runtimeBasePath;
 	let isBuild = false;
+	let isRelease = false;
 	let resolvedConfig;
 	let environmentName;
+	let localAuth = null;
 	return {
 		name: "camox",
 		enforce: "pre",
@@ -103,6 +76,10 @@ function camox(options) {
 			return loadRuntimeDevModule(id, { runtimeBasePath });
 		},
 		nitro: { setup(nitro) {
+			if (nitro.options.noExternals !== true) {
+				const noExternals = Array.isArray(nitro.options.noExternals) ? nitro.options.noExternals : [];
+				nitro.options.noExternals = [...noExternals, "camox"];
+			}
 			installRuntimeNitroRoutes(nitro, { runtimeBasePath });
 			nitro.hooks.hook("compiled", ({ options }) => {
 				const serverAssets = join(options.output.serverDir, "assets");
@@ -112,7 +89,13 @@ function camox(options) {
 		} },
 		config(_config, env) {
 			isBuild = env.command === "build";
-			environmentName = resolveEnvironmentName(env.command, authenticationUrl);
+			isRelease = isBuild && process.env.CAMOX_INTERNAL_RELEASE === "1";
+			if (isRelease) environmentName = "production";
+			else {
+				localAuth = readAuthTokenForUrl(authenticationUrl);
+				if (isBuild && !localAuth) throw new Error("Camox: not authenticated. Run `npx camox login` before building the site.");
+				environmentName = localAuth ? `dev:${localAuth.email}` : "dev:unauthenticated";
+			}
 			return {
 				build: { emitAssets: true },
 				define: {
@@ -220,32 +203,39 @@ function camox(options) {
 			if (!disableCodeGen) {
 				generateAppFile(config.root);
 				cleanupGeneratedRouteFiles(routesDir);
-				generateSkillFiles(config.root);
 			}
 			if (disableCodeGen) config.logger.warn("⚠️  Code generation is disabled (_internal.disableCodeGen). This option is only meant for momentary debugging — do not deploy or commit your app with it enabled.", { timestamp: true });
 			const mode = config.command === "serve" ? "Running" : "Building";
-			config.logger.info(`${mode} Camox app (environment: ${environmentName})`, { timestamp: true });
+			const environmentLabel = localAuth || isRelease ? environmentName : "authentication required";
+			config.logger.info(`${mode} Camox app (${environmentLabel})`, { timestamp: true });
 		},
 		configureServer(server) {
 			const routesDir = resolve(server.config.root, "src/routes");
+			installDevAuthenticationMiddleware(server, {
+				apiUrl,
+				authenticationUrl,
+				isAuthenticated: localAuth !== null
+			});
 			if (!disableCodeGen) {
 				watchAppFile(server, server.config.root);
 				cleanupGeneratedRouteFiles(routesDir);
-				watchSkillFiles(server, server.config.root);
 				watchNewBlockFiles(server);
 			}
 			server.httpServer?.once("listening", () => {
+				if (!localAuth) return;
 				syncDefinitions(server, {
 					projectSlug: options.projectSlug,
-					syncSecret: options.syncSecret,
 					apiUrl,
 					environmentName,
-					autoCreate: true
+					autoCreate: true,
+					authToken: localAuth?.token
 				});
 			});
 		},
 		async closeBundle() {
-			if (!isBuild) return;
+			if (!isRelease) return;
+			const deployToken = process.env.CAMOX_DEPLOY_TOKEN;
+			if (!deployToken) throw new Error("Camox: CAMOX_DEPLOY_TOKEN is required to release to production.");
 			const camoxAppPath = "./src/camox/app.ts";
 			const tempServer = await createServer({
 				configFile: false,
@@ -262,9 +252,9 @@ function camox(options) {
 					camoxApp: camoxModule.camoxApp,
 					projectSlug: options.projectSlug,
 					apiUrl,
-					syncSecret: options.syncSecret,
 					environmentName,
 					autoCreate: false,
+					deployToken,
 					logger: resolvedConfig.logger
 				});
 			} finally {

package/dist/lib/api-client-server.js

@@ -2,9 +2,10 @@ import { createORPCClient } from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
 
 //#region src/lib/api-client-server.ts
-function createServerApiClient(apiUrl, environmentName) {
+function createServerApiClient(apiUrl, environmentName, authToken) {
 	const headers = {};
 	if (environmentName) headers["x-environment-name"] = environmentName;
+	if (authToken) headers.Authorization = `Bearer ${authToken}`;
 	return createORPCClient(new RPCLink({
 		url: `${apiUrl}/rpc`,
 		headers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camox",
-  "version": "0.36.2",
+  "version": "0.38.0",
   "license": "MIT",
   "bin": {
     "camox": "./bin/camox.mjs"
@@ -13,103 +13,83 @@
   "type": "module",
   "exports": {
     "./createApp": {
-      "source": "./src/core/createApp.ts",
       "types": "./dist/core/createApp.d.ts",
       "import": "./dist/core/createApp.js"
     },
     "./createBlock": {
-      "source": "./src/core/createBlock.tsx",
       "types": "./dist/core/createBlock.d.ts",
       "import": "./dist/core/createBlock.js"
     },
     "./createLayout": {
-      "source": "./src/core/createLayout.tsx",
       "types": "./dist/core/createLayout.d.ts",
       "import": "./dist/core/createLayout.js"
     },
     "./document": {
-      "source": "./src/core/defineDocument.ts",
       "types": "./dist/core/defineDocument.d.ts",
       "import": "./dist/core/defineDocument.js"
     },
     "./CamoxPreview": {
-      "source": "./src/features/preview/CamoxPreview.tsx",
       "types": "./dist/features/preview/CamoxPreview.d.ts",
       "import": "./dist/features/preview/CamoxPreview.js"
     },
     "./CamoxContent": {
-      "source": "./src/features/content/CamoxContent.tsx",
       "types": "./dist/features/content/CamoxContent.d.ts",
       "import": "./dist/features/content/CamoxContent.js"
     },
     "./CamoxProvider": {
-      "source": "./src/features/provider/CamoxProvider.tsx",
       "types": "./dist/features/provider/CamoxProvider.d.ts",
       "import": "./dist/features/provider/CamoxProvider.js"
     },
     "./CamoxStudio": {
-      "source": "./src/features/studio/CamoxStudio.tsx",
       "types": "./dist/features/studio/CamoxStudio.d.ts",
       "import": "./dist/features/studio/CamoxStudio.js"
     },
     "./navigation": {
-      "source": "./src/features/navigation/navigation.tsx",
       "types": "./dist/features/navigation/navigation.d.ts",
       "import": "./dist/features/navigation/navigation.js"
     },
     "./vite": {
-      "source": "./src/features/vite/vite.ts",
       "types": "./dist/features/vite/vite.d.ts",
       "import": "./dist/features/vite/vite.js"
     },
     "./metadata": {
-      "source": "./src/features/metadata/sitemap.ts",
       "types": "./dist/features/metadata/sitemap.d.ts",
       "import": "./dist/features/metadata/sitemap.js"
     },
     "./_internal/pageServer": {
-      "source": "./src/features/runtime/pageServer.tsx",
       "types": "./dist/features/runtime/pageServer.d.ts",
       "import": "./dist/features/runtime/pageServer.js"
     },
     "./_internal/pageClient": {
-      "source": "./src/features/runtime/pageClient.tsx",
       "types": "./dist/features/runtime/pageClient.d.ts",
       "import": "./dist/features/runtime/pageClient.js"
     },
     "./_internal/studioClient": {
-      "source": "./src/features/runtime/studioClient.tsx",
       "types": "./dist/features/runtime/studioClient.d.ts",
       "import": "./dist/features/runtime/studioClient.js"
     },
     "./_internal/studioServer": {
-      "source": "./src/features/runtime/studioServer.tsx",
       "types": "./dist/features/runtime/studioServer.d.ts",
       "import": "./dist/features/runtime/studioServer.js"
     },
     "./_internal/runtime": {
-      "source": "./src/features/runtime/runtime.ts",
       "types": "./dist/features/runtime/runtime.d.ts",
       "import": "./dist/features/runtime/runtime.js"
     },
     "./_internal/imageResponse": {
       "workerd": {
-        "source": "./src/features/og/imageResponse.workerd.ts",
         "types": "./dist/features/og/imageResponse.workerd.d.ts",
         "import": "./dist/features/og/imageResponse.workerd.js"
       },
       "worker": {
-        "source": "./src/features/og/imageResponse.workerd.ts",
         "types": "./dist/features/og/imageResponse.workerd.d.ts",
         "import": "./dist/features/og/imageResponse.workerd.js"
       },
       "deno": {
-        "source": "./src/features/og/imageResponse.workerd.ts",
         "types": "./dist/features/og/imageResponse.workerd.d.ts",
         "import": "./dist/features/og/imageResponse.workerd.js"
       },
       "default": {
-        "source": "./src/features/og/imageResponse.node.ts",
         "types": "./dist/features/og/imageResponse.node.d.ts",
         "import": "./dist/features/og/imageResponse.node.js"
       }
@@ -157,9 +137,9 @@
     "streamdown": "^2.5.0",
     "unhead": "^3.1.7",
     "zod": "^4.4.3",
-    "@camox/cli": "0.36.2",
-    "@camox/ui": "0.36.2",
-    "@camox/api-contract": "0.36.2"
+    "@camox/api-contract": "0.38.0",
+    "@camox/cli": "0.38.0",
+    "@camox/ui": "0.38.0"
   },
   "devDependencies": {
     "@babel/core": "^7.29.0",

package/skills/camox/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: camox
+description: Use when working in a Camox codebase with Block Definitions, Layout Definitions, Pages, Block content, the Camox CLI, publishing, or Environments. Applies to code-defined site structure and agent-driven content changes.
+---
+
+# Camox
+
+Load only the references needed for the current task. Do not preload every reference.
+
+- To create or change a **Block Definition** in `src/blocks/`, read [references/block-definitions.md](references/block-definitions.md).
+- To create or change a **Layout Definition** in `src/layouts/`, read [references/layout-definitions.md](references/layout-definitions.md).
+- For any CLI operation, first read [references/cli-common.md](references/cli-common.md), then read only the relevant command reference:
+  - To inspect, create, edit, move, or delete Block instances or their Content, read [references/cli-blocks.md](references/cli-blocks.md).
+  - To inspect, create, update, publish, or assign Layouts to Pages, read [references/cli-pages.md](references/cli-pages.md).
+  - To target production or replicate content between Environments, read [references/cli-environments.md](references/cli-environments.md).
+
+A request can cross boundaries. For example, adding a new kind of section to a Page may require the Block Definition reference followed by the CLI common and Block references. Load the additional reference only once that need is established.

package/skills/{camox-block/SKILL.md → camox/references/block-definitions.md}

@@ -1,15 +1,10 @@
----
-name: camox-block
-description: "How to create Camox block definition files. Use this skill whenever the user wants to create a new block for their Camox website, add a page section/component, build a reusable content block, or asks about the block definition API. Trigger on mentions of blocks, sections, page components, content types, or any request to add new visual sections to a Camox site — even if they don't say 'block' explicitly."
----
-
 # Creating Camox Block Definitions
 
 A block is a reusable page section (hero, testimonial, gallery, footer...). Users compose pages by assembling blocks. This skill covers creating block **definitions** — the template that describes a block's schema and rendering. Not the content (an instance of a block).
 
-## After defining the block: load `camox-cli`
+## After defining the block: place it when requested
 
-A definition only adds a new _type_ of block to the catalog — it doesn't put one on any page. Users almost never just want "a definition"; they want a section that actually shows up on the site. Once the block is defined and the dev server has picked it up, **load the `camox-cli` skill** to create an instance on the relevant page (or to wire it into a layout's `before`/`after` slot via `camox-layout` if it's chrome). If the user asks for "a hero on the homepage", the work is: define the block here, then create a hero block on the home page via the CLI. Don't stop after the definition — that leaves a dangling block type the user has to place by hand.
+A definition only adds a new _type_ of block to the catalog — it doesn't put one on any Page. Users almost never just want "a definition"; they want a section that actually shows up on the site. Once the Block Definition exists and the dev server has picked it up, follow the umbrella skill's CLI routing to create a Block on the relevant Page. For shared chrome, follow the Layout Definition reference instead. If the user asks for "a hero on the homepage", define the Block Definition and then create the hero Block on the home Page. Don't stop after the definition unless the user explicitly requested only the reusable type.
 
 ## Quick Start
 

package/skills/camox/references/cli-blocks.md

@@ -0,0 +1,78 @@
+# Managing Blocks with the Camox CLI
+
+Read [cli-common.md](cli-common.md) first. Replace `{{CAMOX_CMD}}` as described there and verify commands with `--help`.
+
+Use these commands for Block instances and their Content. To change which fields or rendering a Block type provides, use the Block Definition reference instead.
+
+## Inspect before changing
+
+Look up the Page before creating or moving Blocks so you have its `id`, current Blocks, and any sibling ids. Describe the Block type before constructing Content:
+
+```sh
+{{CAMOX_CMD}} pages get --path /
+{{CAMOX_CMD}} blocks describe --type hero
+```
+
+## Create and position a Block
+
+```sh
+{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}'
+{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}' --position first
+{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}' --before-id 174
+{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}' --after-id 174
+```
+
+`blocks create` and `blocks move` accept the same positioning flags. Pass at most one:
+
+| Flag                      | Meaning                                         |
+| ------------------------- | ----------------------------------------------- |
+| `--position first`        | Put the Block first.                            |
+| `--position last`         | Put the Block last; this is the create default. |
+| `--after-id <ID>`         | Put it immediately after a sibling Block.       |
+| `--before-id <ID>`        | Put it immediately before a sibling Block.      |
+| `--after-position <KEY>`  | Insert after a known fractional-index key.      |
+| `--before-position <KEY>` | Insert before a known fractional-index key.     |
+
+Prefer `--position`, `--after-id`, and `--before-id`. A move requires one positioning flag.
+
+## Edit Block Content
+
+Content patches merge ordinary fields, so send only fields that should change:
+
+```sh
+{{CAMOX_CMD}} pages get --path /pricing
+{{CAMOX_CMD}} blocks edit --id 314 --content '{"headline": "New headline"}'
+```
+
+## Edit repeatable Content safely
+
+A repeatable field's array is replacement-shaped: omitting an existing item deletes it and cascades to its file references, settings, and nested items. Fetch the Block, preserve every existing item with `_itemId`, and add changes only to the intended entries:
+
+```sh
+{{CAMOX_CMD}} blocks get --id 99
+
+{{CAMOX_CMD}} blocks edit --id 99 --content '{
+  "items": [
+    {"_itemId": 401},
+    {"_itemId": 402, "answer": "Updated answer."},
+    {"_itemId": 403}
+  ]
+}'
+```
+
+The response's `repeatableItems` contains each item's `id`, `fieldName`, `parentItemId`, and Content. Use the same `_itemId` pattern recursively for nested repeatables. Fetch multiple Blocks together when useful:
+
+```sh
+{{CAMOX_CMD}} blocks get-many --id 99 --id 100 --id 101
+```
+
+`blocks get-many` returns the same bundle shape as `blocks get`, in requested-id order.
+
+## Draft and live reads
+
+```sh
+{{CAMOX_CMD}} blocks get --id 314        # draft
+{{CAMOX_CMD}} blocks get --id 314 --live # published snapshot
+```
+
+Publish or discard at the Page level; read [cli-pages.md](cli-pages.md) when the task includes review or publication.

package/skills/camox/references/cli-common.md

@@ -0,0 +1,48 @@
+# Camox CLI common guidance
+
+Use the Camox CLI for CRUD operations on Pages, Block instances, Layout assignments, metadata, drafts, and published content. Use the code references instead when changing Block Definitions or Layout Definitions in `src/blocks/` or `src/layouts/`.
+
+If a change should be visible without a code deployment, it is usually a CLI content operation. Some requests require both code and CLI work: define the new type first, wait for the dev server to discover it, then create or assign its content through the CLI.
+
+## Run the installed CLI
+
+Detect the package manager from the closest `package.json#packageManager` or lockfile, then use its local Camox binary:
+
+| Package manager | Command      |
+| --------------- | ------------ |
+| pnpm            | `pnpm camox` |
+| Bun             | `bunx camox` |
+| npm             | `npx camox`  |
+
+In the examples below, replace `{{CAMOX_CMD}}` with that command.
+
+## Discover the current command surface
+
+The CLI evolves with the installed Camox version. Do not guess commands or flags from memory. Run `--help` at the root, command group, and subcommand before executing a write:
+
+```sh
+{{CAMOX_CMD}} --help
+{{CAMOX_CMD}} pages --help
+{{CAMOX_CMD}} pages create --help
+```
+
+Treat the installed CLI's output as authoritative when it differs from an example in these references.
+
+## Draft-first workflow
+
+By default, reads and writes operate on the draft in the current developer's isolated dev Environment. Make content changes in draft, summarize them for review, and publish only after the user asks or approves.
+
+- Omit `--live` while editing. `--live` only reads the published snapshot.
+- Omit `--production` unless the user explicitly asks to operate on the production Environment.
+- Publishing a draft and replicating an Environment are different operations. Read the Environment reference before using `env push` or `env pull`.
+
+## Write grounded content
+
+Before writing Content:
+
+1. Inspect existing Pages, Blocks, and Block type descriptions to learn the site's voice, positioning, names, and factual claims.
+2. Use facts and copy supplied by the user. Research external facts with an available retrieval tool; ask when a material fact cannot be established.
+3. Never invent filler copy, statistics, testimonials, company details, asset filenames, or URLs.
+4. Leave `File`, `Embed`, or `Image` values empty when no real asset is available, and tell the user what remains to be supplied.
+
+After writes, report the affected Pages and Blocks and the notable content or structural changes.

package/skills/camox/references/cli-environments.md

@@ -0,0 +1,37 @@
+# Managing Environments with the Camox CLI
+
+Read [cli-common.md](cli-common.md) first. Replace `{{CAMOX_CMD}}` as described there and verify commands with `--help`.
+
+Every Project has an isolated dev Environment for each developer and a shared production Environment. Each Environment independently contains draft and live sources.
+
+## Target production per command
+
+Commands target the dev Environment by default. Use `--production` only when the user explicitly asks to operate on production:
+
+```sh
+{{CAMOX_CMD}} pages list --production
+{{CAMOX_CMD}} blocks edit --id <ID> --production
+```
+
+`--production` selects the Environment; it does not select published content. Combine it with `--live` to read production's published snapshot, or use `pages publish --production` to publish a production draft.
+
+## Replicate an entire Environment
+
+Use the `env` group when the user wants to copy all dev content to production or replace dev with production. Do not emulate replication with a series of resource commands.
+
+Inspect compatibility first:
+
+```sh
+{{CAMOX_CMD}} env check
+```
+
+`env check` reports push and pull compatibility and identifies Block Definition or Layout divergences. Resolve every reported divergence before replication; incompatible replication fails with `FAILED_PRECONDITION` and the same reasons.
+
+After explicit user authorization for the requested direction:
+
+```sh
+{{CAMOX_CMD}} env push --yes # replace production with dev
+{{CAMOX_CMD}} env pull --yes # replace dev with production
+```
+
+Both operations replace every Page, Block, and file in the target Environment and cannot be undone. They require `--yes` or `-y`. Confirm the direction from the user's request; never infer push versus pull.

package/skills/camox/references/cli-pages.md

@@ -0,0 +1,53 @@
+# Managing Pages with the Camox CLI
+
+Read [cli-common.md](cli-common.md) first. Replace `{{CAMOX_CMD}}` as described there and verify commands with `--help`.
+
+Use these commands for Page paths and metadata, Layout assignments, draft review, and publishing. Use [cli-blocks.md](cli-blocks.md) when changing the ordered Blocks or Content on a Page.
+
+## Create a Page with an existing Layout
+
+```sh
+{{CAMOX_CMD}} layouts list
+{{CAMOX_CMD}} pages create --path-segment about --layout-id 39
+```
+
+Use `--parent-page-id <ID>` to nest the Page under another Page. Assigning an existing Layout is a CLI content operation; creating or changing a Layout Definition is a code operation covered by the Layout Definition reference.
+
+## Review draft and live state
+
+```sh
+{{CAMOX_CMD}} pages get --path /pricing        # draft
+{{CAMOX_CMD}} pages get --path /pricing --live # published snapshot
+```
+
+Live reads fail when the Page or Block has never been published. `--live` is not a write target and does not publish anything.
+
+## Publish after approval
+
+```sh
+{{CAMOX_CMD}} pages publish --path /pricing
+```
+
+`pages publish` accepts exactly one of `--id` or `--path`. It publishes the Page's current draft and, by default, its Layout. Publishing the Layout is a no-op when it has no pending changes. Use `--no-layout` only when the user explicitly does not want pending Layout changes published with the Page:
+
+```sh
+{{CAMOX_CMD}} pages publish --path /pricing --no-layout
+```
+
+Do not publish merely because a draft edit succeeded. Summarize the draft and wait for the user to ask or approve publication.
+
+## Unpublish or discard drafts
+
+Remove a Page from live without deleting its draft:
+
+```sh
+{{CAMOX_CMD}} pages unpublish --path /pricing
+```
+
+Reset a draft to its current live snapshot without changing live:
+
+```sh
+{{CAMOX_CMD}} pages discard-changes --path /pricing
+```
+
+Both commands accept exactly one of `--id` or `--path`. Discarding fails if the Page has never been published.

package/skills/{camox-layout/SKILL.md → camox/references/layout-definitions.md}

@@ -1,15 +1,10 @@
----
-name: camox-layout
-description: "How to create and edit Camox layout definition files. Use this skill whenever the user wants to create a new layout for their Camox website, modify an existing layout, wrap pages in shared structure (navbar + footer), customize meta titles or OG images, or asks about the layout definition API. Trigger on mentions of layouts, page wrappers, page templates, shared page structure, navbar/footer placement, or any request to define how pages are structured — even if they don't say 'layout' explicitly."
----
-
 # Creating Camox Layout Definitions
 
 A layout wraps pages in shared structure — a navbar at the top, a footer at the bottom, consistent styling. Each page in the CMS is assigned a layout. This skill covers creating layout **definitions** — the template that describes which blocks surround page content and how to render them.
 
-## After defining the layout: load `camox-cli`
+## After defining the layout: assign it when requested
 
-A definition only adds a new layout to the catalog — it doesn't apply it to any page, and existing pages keep whatever layout they were already assigned. If the user wanted "the about page to use the new marketing layout" or "all docs pages to use this layout", the second half of that work is reassigning pages, which happens through the CLI. Once the layout is defined and the dev server has picked it up, **load the `camox-cli` skill** to update the relevant pages' layout assignments. Don't stop after the definition unless the user explicitly only wanted to set up the layout for future pages.
+A definition only adds a new Layout to the catalog — it doesn't apply it to any Page, and existing Pages keep their current Layout. If the user wanted "the about Page to use the new marketing Layout" or "all docs Pages to use this Layout", follow the umbrella skill's CLI routing to update the relevant Pages after the dev server has picked up the definition. Don't stop after the definition unless the user explicitly requested only a reusable Layout Definition.
 
 ## Quick Start
 

package/dist/features/vite/skillGeneration.js

@@ -1,104 +0,0 @@
-import { writeIfChanged } from "./utils.js";
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, symlinkSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-//#region src/features/vite/skillGeneration.ts
-const NOTICE = `<!-- AUTO-GENERATED BY CAMOX — DO NOT EDIT
-This file is managed by the Camox Vite plugin.
-Any manual edits will be automatically reverted by the dev server. -->`;
-function injectNoticeAfterFrontmatter(source) {
-	if (!source.startsWith("---\n")) return `${NOTICE}\n\n${source}`;
-	const closeIdx = source.indexOf("\n---\n", 4);
-	if (closeIdx === -1) return `${NOTICE}\n\n${source}`;
-	const endOfClose = closeIdx + 5;
-	return `${source.slice(0, endOfClose)}\n${NOTICE}\n${source.slice(endOfClose)}`;
-}
-const sdkRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
-const camoxCmdByPm = {
-	pnpm: "pnpm camox",
-	bun: "bunx camox",
-	npm: "npx camox"
-};
-function detectPackageManagerInDir(dir) {
-	const packageJsonPath = resolve(dir, "package.json");
-	if (existsSync(packageJsonPath)) try {
-		const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
-		const name = (typeof pkg.packageManager === "string" ? pkg.packageManager : "").split("@", 1)[0];
-		if (name === "pnpm" || name === "bun" || name === "npm") return name;
-	} catch {}
-	if (existsSync(resolve(dir, "pnpm-lock.yaml"))) return "pnpm";
-	if (existsSync(resolve(dir, "bun.lock")) || existsSync(resolve(dir, "bun.lockb"))) return "bun";
-	if (existsSync(resolve(dir, "package-lock.json"))) return "npm";
-}
-function detectPackageManager(appRoot) {
-	let dir = resolve(appRoot);
-	while (true) {
-		const found = detectPackageManagerInDir(dir);
-		if (found) return found;
-		const parent = dirname(dir);
-		if (parent === dir) return "npm";
-		dir = parent;
-	}
-}
-function getSkillNames() {
-	const skillsDir = resolve(sdkRoot, "skills");
-	return readdirSync(skillsDir).filter((name) => lstatSync(resolve(skillsDir, name)).isDirectory());
-}
-function generateSkillContent(skillName, appRoot) {
-	const raw = readFileSync(resolve(sdkRoot, `skills/${skillName}/SKILL.md`), "utf-8");
-	const pm = detectPackageManager(appRoot);
-	return injectNoticeAfterFrontmatter(raw.replaceAll("{{PM_NAME}}", pm).replaceAll("{{CAMOX_CMD}}", camoxCmdByPm[pm]));
-}
-function getSkillFileEntries(appRoot) {
-	return getSkillNames().map((name) => ({
-		path: resolve(appRoot, `.agents/skills/${name}/SKILL.md`),
-		content: generateSkillContent(name, appRoot)
-	}));
-}
-function generateSkillFiles(appRoot) {
-	for (const name of getSkillNames()) mkdirSync(resolve(appRoot, `.agents/skills/${name}`), { recursive: true });
-	for (const entry of getSkillFileEntries(appRoot)) writeIfChanged(entry.path, entry.content);
-	ensureClaudeSkillSymlinks(appRoot);
-}
-/**
-* For each skill directory in `.agents/skills/`, ensure a corresponding
-* symlink exists in `.claude/skills/` pointing to it via a relative path.
-*/
-function ensureClaudeSkillSymlinks(appRoot) {
-	const agentsSkillsDir = resolve(appRoot, ".agents/skills");
-	const claudeSkillsDir = resolve(appRoot, ".claude/skills");
-	mkdirSync(claudeSkillsDir, { recursive: true });
-	for (const name of readdirSync(agentsSkillsDir)) {
-		if (!lstatSync(join(agentsSkillsDir, name)).isDirectory()) continue;
-		const symlinkPath = join(claudeSkillsDir, name);
-		const targetRelative = join("../../.agents/skills", name);
-		try {
-			if (readlinkSync(symlinkPath) === targetRelative) continue;
-		} catch {}
-		symlinkSync(targetRelative, symlinkPath);
-	}
-}
-function watchSkillFiles(server, appRoot) {
-	const entries = getSkillFileEntries(appRoot);
-	const expectedByPath = new Map(entries.map((e) => [e.path, e.content]));
-	server.watcher.on("change", (changedPath) => {
-		const expected = expectedByPath.get(changedPath);
-		if (!expected) return;
-		if (readFileSync(changedPath, "utf-8") !== expected) {
-			const rel = relative(server.config.root, changedPath);
-			server.config.logger.warn(`Camox skill file "${rel}" was modified — reverting to generated version.`, { timestamp: true });
-			writeFileSync(changedPath, expected, "utf-8");
-		}
-	});
-	server.watcher.on("unlink", (deletedPath) => {
-		const expected = expectedByPath.get(deletedPath);
-		if (!expected) return;
-		const rel = relative(server.config.root, deletedPath);
-		server.config.logger.warn(`Camox skill file "${rel}" was deleted — recreating.`, { timestamp: true });
-		writeFileSync(deletedPath, expected, "utf-8");
-	});
-}
-
-//#endregion
-export { generateSkillFiles, watchSkillFiles };

package/skills/camox-cli/SKILL.md

@@ -1,268 +0,0 @@
----
-name: camox-cli
-description: "How to read or modify Camox website content via the CLI: pages, routes, block instances, copy, images/files, meta fields, layout assignments, draft/live state, publishing, and dev/prod sync. Use when the user wants to add, remove, rename, reorder, review, publish, or change anything visible on the site, including sections, heroes, footers, headlines, SEO titles, social previews, or what appears at a URL. Trigger on requests like 'add a page', 'change the headline', 'move this section', 'what's on /about', 'show me the live page', 'publish this page', 'fix the meta title', 'push to production', 'pull from production', or 'sync dev with prod', even if they do not mention Camox, CMS, page, block, layout, environment, or CLI."
----
-
-# Using the Camox CLI
-
-The Camox CLI is the right tool for any **CRUD operation on CMS content** — pages, block instances, layout assignments, meta fields. Reach for it before writing a custom script or asking the user to click through the dashboard. The `camox` binary is already installed in this project (it ships with the `camox` package).
-
-## When to use this skill vs. `camox-block` / `camox-layout`
-
-This skill (`camox-cli`) is for **content** — the actual pages, the actual block instances on those pages, the wording and images visitors see. If the user wants to add a section to a specific page, change copy, reorder blocks, create a new route, swap which layout a page uses, or fix a meta title, you're editing content and you want the CLI.
-
-The `camox-block` skill is for **block definitions** — the `.tsx` files in `src/blocks/` that define what _kinds_ of blocks exist (their schema, fields, and rendering). Reach for it only when the user wants to introduce a new type of section that doesn't exist yet (e.g. "we need a pricing-table section and we've never built one"), or change the schema or rendering of an existing block type.
-
-The `camox-layout` skill is for **layout definitions** — the `.tsx` files in `src/layouts/` that define the shared shells around page content (which navbar/footer blocks wrap pages, how meta titles are built, OG images, etc.). Reach for it when the user wants a new kind of page wrapper, a different shared structure, or to change how titles or social previews are constructed. _Assigning_ an existing layout to a page is content — that's the CLI.
-
-Rule of thumb: if the change should be visible on the live site without a code deploy, it's content → use the CLI. If it requires editing source files in `src/blocks/` or `src/layouts/`, it's a definition → use `camox-block` or `camox-layout`. Some requests need both (e.g. "add a pricing section the site has never had before" = define the block via `camox-block`, then create an instance on a page via the CLI).
-
-## Running the CLI
-
-This project uses **{{PM_NAME}}**. Always invoke the CLI as:
-
-```sh
-{{CAMOX_CMD}} <command> [options]
-```
-
-For example: `{{CAMOX_CMD}} pages list`, `{{CAMOX_CMD}} blocks types`.
-
-## Discover commands with `--help`
-
-The CLI surface evolves. **Don't guess command names or flags from memory — ask the CLI.** Run `--help` at the root and on every subcommand before invoking it, and treat the output as authoritative.
-
-```sh
-# top-level: lists command groups (pages, blocks, layouts, ...)
-{{CAMOX_CMD}} --help
-
-# a group: lists its subcommands
-{{CAMOX_CMD}} pages --help
-
-# a subcommand: lists its required and optional flags
-{{CAMOX_CMD}} pages create --help
-```
-
-The CLI is organised into command groups around the resource types (pages, blocks, layouts, …). Use `--help` to discover what each group supports — the exact set of subcommands and flags is the CLI's responsibility, not this skill's.
-
-## Common recipes
-
-Most content tasks fit into a small number of shapes. Use these as the entry-point template, then verify exact flags with `--help`. Always look up the page (`pages get`) before you create or move blocks — you'll need its `id` and the `id` / `type` of any sibling block you're positioning relative to.
-
-### Add a new block at a specific spot on a page
-
-```sh
-# 1) Find the page and the sibling you'll position relative to.
-{{CAMOX_CMD}} pages get --path /
-# read the response to grab pageId and the id of the existing first block
-
-# 2) See what fields the block type accepts.
-{{CAMOX_CMD}} blocks describe --type hero
-
-# 3) Create the new block at the desired position.
-# At the very top of the page:
-{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}' --position first
-# Or right before / after a known sibling:
-{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}' --before-id 174
-{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}' --after-id 174
-# Or appended to the end (default):
-{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}'
-```
-
-See **Block positioning** below for the full set of options.
-
-### Update copy in an existing block
-
-```sh
-# 1) Locate the block on the page.
-{{CAMOX_CMD}} pages get --path /pricing
-# note the block id you want to edit
-
-# 2) Patch only the fields you want to change — content is merged.
-{{CAMOX_CMD}} blocks edit --id 314 --content '{"headline": "New headline"}'
-```
-
-### Update one item inside a repeatable field (one FAQ answer, one feature title, …)
-
-Repeatable fields are an array of items. `blocks edit` treats the items array as the new truth: any existing item whose `_itemId` is not in your patch is **deleted** (cascading to its file references, settings, and child items). To change one item without losing the rest, fetch the block first to learn every item's id, then patch with every `_itemId` present.
-
-```sh
-# 1) Fetch the block's raw items (the `id` of each is its `_itemId`).
-{{CAMOX_CMD}} blocks get --id 99
-# in the response, `repeatableItems` lists each item with `id`, `fieldName`,
-# `parentItemId`, and `content`. Pick the id you want to edit.
-
-# 2) Send every item back. Empty `{"_itemId": N}` entries preserve items as-is;
-# the entry you want to change carries the field overrides.
-{{CAMOX_CMD}} blocks edit --id 99 --content '{
-  "items": [
-    {"_itemId": 401},
-    {"_itemId": 402, "answer": "Updated answer."},
-    {"_itemId": 403}
-  ]
-}'
-```
-
-Same pattern for nested repeatables: each child item also has an `id` you pass back as `_itemId` inside the parent item's array field.
-
-When you need to edit repeatable fields in several blocks, prefer fetching them together first:
-
-```sh
-{{CAMOX_CMD}} blocks get-many --id 99 --id 100 --id 101
-```
-
-`blocks get-many` returns the same bundle shape as `blocks get` for each block, in the same order as the requested ids.
-
-### Create a new page using an existing layout
-
-```sh
-# 1) List layouts and pick one.
-{{CAMOX_CMD}} layouts list
-
-# 2) Create the page under that layout.
-{{CAMOX_CMD}} pages create --path-segment about --layout-id 39
-# Use --parent-page-id <ID> to nest the page under another route.
-```
-
-### Review a draft and publish it to live
-
-Agents should work on **drafts** first, get the changes reviewed, and only then publish. Draft is the default source for reads and the default target for writes, so do not add `--live` while editing.
-
-```sh
-# 1) Inspect the draft the agent will edit/review.
-{{CAMOX_CMD}} pages get --path /pricing
-{{CAMOX_CMD}} blocks get --id 314
-
-# 2) Inspect the currently published snapshot when you need a before/after.
-{{CAMOX_CMD}} pages get --path /pricing --live
-{{CAMOX_CMD}} blocks get --id 314 --live
-
-# 3) After review/approval, publish the draft page to live.
-{{CAMOX_CMD}} pages publish --path /pricing
-
-# Use --no-layout only when you explicitly do not want to publish pending
-# changes to the page's layout alongside the page.
-{{CAMOX_CMD}} pages publish --path /pricing --no-layout
-```
-
-`pages publish` accepts exactly one of `--id` or `--path`. It publishes the page's current draft. By default it also publishes the page's layout; that layout publish is a no-op when there are no pending layout changes.
-
-To remove a published page from live without deleting its draft:
-
-```sh
-{{CAMOX_CMD}} pages unpublish --path /pricing
-```
-
-To throw away unpublished draft edits and reset the draft to the current live snapshot:
-
-```sh
-{{CAMOX_CMD}} pages discard-changes --path /pricing
-```
-
-`pages unpublish` and `pages discard-changes` accept exactly one of `--id` or `--path`. `pages unpublish` leaves the draft untouched. `pages discard-changes` does not change live content and fails when the page has never been published.
-
-`--live` is for **reading** the published snapshot. It is not a write target and it is not how you publish. Live reads error when the page or block has never been published.
-
-### Promote dev to production (or pull production back into dev)
-
-The `env` group replicates content in bulk between your dev environment and production — the same two operations the studio's environment menu exposes. This is separate from draft/live publishing. Use it when the user wants to copy an environment's content to the other environment, or wipe dev and start from production.
-
-```sh
-# Inspect both directions before committing. Shows whether push/pull are
-# currently safe, and lists any block-definition / layout divergences if not.
-{{CAMOX_CMD}} env check
-
-# Overwrite production with your dev environment.
-{{CAMOX_CMD}} env push --yes
-
-# Overwrite your dev environment with production.
-{{CAMOX_CMD}} env pull --yes
-```
-
-`--yes` (or `-y`) is required on `push` / `pull` — both replace every page, block, and file in the target environment and the change cannot be undone. See **Environments, drafts, and live** below for when to use this vs `pages publish`, `--live`, and `--production`.
-
-## Block positioning
-
-`blocks create` and `blocks move` accept the same set of positioning flags. **Pass at most one** — combining them is rejected. `move` requires one (use `--position last` to send a block to the end); `create` defaults to appending at the end if you pass none.
-
-| Flag                      | Meaning                                                              |
-| ------------------------- | -------------------------------------------------------------------- |
-| `--position first`        | Place at the very top of the page.                                   |
-| `--position last`         | Place at the very bottom of the page (also the create-time default). |
-| `--after-id <ID>`         | Place immediately after the sibling block with that id.              |
-| `--before-id <ID>`        | Place immediately before the sibling block with that id.             |
-| `--after-position <KEY>`  | Low-level: insert after a known fractional-index key.                |
-| `--before-position <KEY>` | Low-level: insert before a known fractional-index key.               |
-
-Prefer the high-level flags (`--position`, `--after-id`, `--before-id`) — they read naturally and don't require you to know the fractional-index format. The `--after-position` / `--before-position` flags exist for cases where you already have a key in hand (e.g. piping output between commands).
-
-## Environments, drafts, and live
-
-Every project has two environments: a per-user, isolated **dev** environment and the shared **production** environment. Inside each environment, content has a **draft** working copy and a **live** published snapshot.
-
-### Draft-first workflow
-
-By default, reads and writes operate on the draft. This is intentional: agents should make content changes in draft, summarize what changed, let the user review, and publish only after approval.
-
-```sh
-{{CAMOX_CMD}} pages get --path /about       # draft
-{{CAMOX_CMD}} blocks edit --id 314 --content '{"headline": "New headline"}'
-{{CAMOX_CMD}} pages publish --path /about   # after review
-{{CAMOX_CMD}} pages discard-changes --path /about # reset draft to live
-```
-
-Use `--live` only to compare against the published snapshot:
-
-```sh
-{{CAMOX_CMD}} pages get --path /about --live
-{{CAMOX_CMD}} blocks get --id 314 --live
-```
-
-### Per-command: the `--production` flag
-
-By default, every command runs against the dev environment. Pass `--production` to target the production environment instead, one command at a time:
-
-```sh
-{{CAMOX_CMD}} pages list --production
-{{CAMOX_CMD}} blocks edit --id <ID> --production
-```
-
-`--production` selects the environment; it does not mean "published". Production still has draft and live state. To read production's published snapshot, combine `--production` with `--live`. To publish a production draft, use `pages publish --production`.
-
-Only use `--production` when the user has explicitly asked to operate on the production environment. For everything else — exploration, tentative edits, anything you'd want to be able to throw away — stay on the default dev environment.
-
-### Bulk replication: the `env` group
-
-When the user wants to **copy dev to production** (or do the inverse — wipe dev and start from production), use the env group instead of running many commands with `--production`:
-
-```sh
-{{CAMOX_CMD}} env check        # report compatibility of both push and pull
-{{CAMOX_CMD}} env push --yes   # overwrite production with dev
-{{CAMOX_CMD}} env pull --yes   # overwrite dev with production
-```
-
-`env check` returns `{ push: { compatible, reasons }, pull: { compatible, reasons } }`. The `reasons` array is empty when that direction is safe; otherwise each entry names a divergence (a block type or layout that exists in one env but not the other, or a block-definition schema mismatch). Fix the divergence first — replicate will refuse with `FAILED_PRECONDITION` and the same reasons in `data.reasons` if you don't.
-
-`env push` and `env pull` require `--yes` (or `-y`) because they replace the target environment's entire content. Without it the command refuses and prints what it would have done.
-
-## Don't write slop — build understanding first
-
-Anything you create with this CLI ends up on a real website read by real people. **Never invent generic filler copy** ("Welcome to our amazing platform", "Lorem ipsum"-grade headlines, plausible-sounding-but-fabricated stats, made-up testimonials, fake company names). That kind of content is worse than nothing — it ships, it gets indexed, and the user has to clean it up.
-
-Before writing any block content:
-
-1. **Read what already exists.** Use the CLI to list pages and inspect existing blocks (`{{CAMOX_CMD}} pages list`, `{{CAMOX_CMD}} pages get …`, `{{CAMOX_CMD}} blocks describe …`, etc. — discover the exact commands via `--help`). The site's voice, product positioning, naming, and recurring claims are usually already established somewhere; mirror them. A new "About" block on a site that already has hero/feature copy should sound like a continuation of that copy, not a fresh marketing draft.
-2. **Pull real facts from the right source.** If the user gave you the content, use it verbatim. If the content describes something external (a person, company, product, paper, event, library), use web search or whatever fetch tools you have to look up actual details before writing. If you genuinely can't get a fact, ask the user — don't paper over it with a guess.
-3. **For `File` and `Embed` fields, do not guess URLs.** These point at real assets (PDFs, videos, embeds). A hallucinated URL produces a broken link or, worse, a link to someone else's content. Leave the URL field blank and tell the user the asset still needs to be supplied — the CMS will treat the empty value correctly, and `toMarkdown` will skip the line.
-4. **Same for `Image`.** Don't fabricate filenames. If you don't have a real uploaded asset to reference, leave it empty and flag it.
-
-Short version: if you're tempted to "make something up that sounds about right", stop and either go find the real thing or hand the gap back to the user.
-
-## Workflow
-
-1. If the task matches one of the **Common recipes** above, start from that template — it's almost always the right shape.
-2. Otherwise, run `{{CAMOX_CMD}} --help` to find the right command group, then `{{CAMOX_CMD}} <group> --help` and `{{CAMOX_CMD}} <group> <command> --help` to confirm the exact flags.
-3. Before writing content, read existing pages/blocks and gather any external facts you need (see above).
-4. Work on draft first. Omit `--live` while editing; use `--live` only for reading the published snapshot for comparison.
-5. Get the draft changes reviewed. Summarize the affected page(s), block ids, and notable copy/structure changes.
-6. Publish with `{{CAMOX_CMD}} pages publish --id <ID>` or `{{CAMOX_CMD}} pages publish --path <PATH>` only after the user asks or approves.
-7. Add `--production` only when the user has asked to operate on the production environment.