@hitch42/applet 0.1.0-beta.2

package/dist/vite.js

@@ -0,0 +1,358 @@
+import { i as APPLET_CODE_PATTERN, n as appletManifestSchema, r as appletSourceDefinitionSchema } from "./manifest-DyoJ1MIL.js";
+import { i as resolveInstanceUrl, n as organizationInstanceUrl } from "./auth-DaVK0k5R.js";
+import { c as writeClientEntry, i as writeRegisterDeclaration, l as writeManifestGen, r as syncContract, s as writeAppletRoot, u as writeServerEntry } from "./generate-BFmIzHaR.js";
+import { i as resolveWorkspaceOrg } from "./load-config-BnxocLAQ.js";
+import { existsSync } from "node:fs";
+import { appendFile, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { basename, relative, resolve } from "node:path";
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { tanstackRouter } from "@tanstack/router-plugin/vite";
+import react from "@vitejs/plugin-react";
+//#region src/vite.ts
+const APPLET_COMPATIBILITY_DATE = "2026-07-14";
+const APPLET_COMPATIBILITY_FLAGS = ["nodejs_compat"];
+function clientBootstrapScript(parentOrigin, appletCode) {
+	return `(function () {
+  var parentOrigin = ${parentOrigin === void 0 ? "null" : JSON.stringify(parentOrigin)};
+  var appletCode = ${JSON.stringify(appletCode)};
+  var appletCodePattern = ${APPLET_CODE_PATTERN.toString()};
+
+  Object.defineProperty(window, "__hitchCacheContext", {
+    configurable: false,
+    writable: false,
+    value: window.parent !== window && parentOrigin !== null
+      ? fetch("/__applet/context/" + encodeURIComponent(appletCode), {
+          credentials: "same-origin",
+          headers: { accept: "application/json" }
+        }).then(function (response) {
+          if (!response.ok) throw new Error("Applet cache context returned " + response.status + ".");
+          return response.json();
+        }).catch(function (error) {
+          console.error("Could not load the applet cache context.", error);
+          return null;
+        })
+      : null
+  });
+
+  function applyTheme(theme) {
+    document.documentElement.classList.toggle("dark", theme === "dark");
+  }
+
+  function reportLocation() {
+    if (window.parent === window || parentOrigin === null) return;
+    window.parent.postMessage(
+      {
+        type: "hitch:location",
+        href: window.location.pathname + window.location.search + window.location.hash
+      },
+      parentOrigin
+    );
+  }
+
+  var params = new URLSearchParams(window.location.search);
+  var theme = params.get("_hitch_theme");
+  var dark = theme === "dark" ||
+    (theme !== "light" && window.matchMedia("(prefers-color-scheme: dark)").matches);
+  applyTheme(dark ? "dark" : "light");
+  if (params.has("_hitch_theme")) {
+    var cleanUrl = new URL(window.location.href);
+    cleanUrl.searchParams.delete("_hitch_theme");
+    window.history.replaceState(window.history.state, "", cleanUrl);
+  }
+
+  var pushState = window.history.pushState;
+  window.history.pushState = function () {
+    var result = pushState.apply(window.history, arguments);
+    reportLocation();
+    return result;
+  };
+  var replaceState = window.history.replaceState;
+  window.history.replaceState = function () {
+    var result = replaceState.apply(window.history, arguments);
+    reportLocation();
+    return result;
+  };
+  window.addEventListener("popstate", reportLocation);
+  window.addEventListener("hashchange", reportLocation);
+
+  window.addEventListener("message", function (event) {
+    if (
+      event.source !== window.parent ||
+      (parentOrigin !== null && event.origin !== parentOrigin) ||
+      !event.data
+    ) return;
+
+    if (
+      parentOrigin !== null &&
+      event.data.type === "hitch:location-request"
+    ) {
+      reportLocation();
+      return;
+    }
+
+    if (
+      event.data.type === "hitch:theme" &&
+      (event.data.theme === "light" || event.data.theme === "dark")
+    ) {
+      applyTheme(event.data.theme);
+      return;
+    }
+
+    if (
+      parentOrigin !== null &&
+      event.data.type === "hitch:navigation-probe" &&
+      typeof event.data.requestId === "string"
+    ) {
+      window.parent.postMessage(
+        { type: "hitch:navigation-ready", requestId: event.data.requestId },
+        parentOrigin
+      );
+      return;
+    }
+
+    if (
+      parentOrigin === null ||
+      event.data.type !== "hitch:navigate" ||
+      typeof event.data.appletCode !== "string" ||
+      !appletCodePattern.test(event.data.appletCode) ||
+      (event.data.theme !== "light" && event.data.theme !== "dark")
+    ) return;
+
+    var nextHref = typeof event.data.href === "string"
+      ? event.data.href
+      : "/" + event.data.appletCode;
+    var nextUrl = new URL(nextHref, window.location.origin);
+    var nextAppletPath = "/" + event.data.appletCode;
+    if (
+      nextUrl.origin !== window.location.origin ||
+      (nextUrl.pathname !== nextAppletPath && !nextUrl.pathname.startsWith(nextAppletPath + "/"))
+    ) return;
+
+    applyTheme(event.data.theme);
+    if (
+      nextUrl.pathname + nextUrl.search + nextUrl.hash ===
+      window.location.pathname + window.location.search + window.location.hash
+    ) return;
+    nextUrl.searchParams.set("_hitch_theme", event.data.theme);
+    window.location.replace(nextUrl);
+  });
+})();`;
+}
+function applet(sourceDefinition, options = {}) {
+	const parsedSourceDefinition = appletSourceDefinitionSchema.safeParse(sourceDefinition);
+	if (!parsedSourceDefinition.success) {
+		const raw = sourceDefinition;
+		const orgMessage = typeof raw === "object" && raw !== null && "org" in raw ? " org now lives in hitch.config.ts, not in applet.manifest.ts." : "";
+		throw new Error(`applet(): ${parsedSourceDefinition.error.message}${orgMessage}`);
+	}
+	const { dependencies: _dependencies, devDependencies: _devDependencies, ...definition } = parsedSourceDefinition.data;
+	const parsedDefinition = { data: definition };
+	let appletConfig;
+	let buildRootOutDir;
+	let clearedOutDir = false;
+	let contractSync;
+	let themeStylesheetUrl;
+	const virtualRouteConfig = {
+		type: "root",
+		file: "__root.tsx",
+		children: [{
+			type: "physical",
+			directory: ".",
+			pathPrefix: parsedDefinition.data.code
+		}]
+	};
+	const resolveAppletConfig = (root) => {
+		const resolvedRoot = resolve(root);
+		if (appletConfig?.root === resolvedRoot) return appletConfig;
+		const directoryCode = basename(resolvedRoot);
+		if (directoryCode !== parsedDefinition.data.code) throw new Error(`Applet directory "${directoryCode}" does not match code "${parsedDefinition.data.code}". Rename the directory or change the code.`);
+		const org = resolveWorkspaceOrg(resolvedRoot);
+		const routesDirectory = resolve(resolvedRoot, "src/client/routes");
+		const hasClient = existsSync(routesDirectory);
+		const hasServer = existsSync(resolve(resolvedRoot, "src/server/main.ts"));
+		if (!hasServer && (parsedDefinition.data.schedules?.length ?? 0) > 0) throw new Error("An applet with schedules must have src/server/main.ts.");
+		const legacyMain = resolve(resolvedRoot, "src/client/main.tsx");
+		const indexHtml = resolve(resolvedRoot, "index.html");
+		if (hasClient && existsSync(legacyMain)) throw new Error(`Applet client entrypoint must use file-based routes. Move your component into src/client/routes/index.tsx: ${legacyMain}`);
+		if (hasClient && !existsSync(indexHtml)) throw new Error(`Missing index.html at ${indexHtml}. Create it with <div id="root"></div> and <script type="module" src="/.hitch/entry.gen.tsx"><\/script>.`);
+		appletConfig = {
+			root: resolvedRoot,
+			manifest: appletManifestSchema.parse({
+				org,
+				...parsedDefinition.data
+			}),
+			routesDirectory,
+			hasClient,
+			hasAuthorRoot: hasClient && existsSync(resolve(routesDirectory, "__root.tsx")),
+			hasServer,
+			hasRouter: existsSync(resolve(resolvedRoot, "src/client/router.tsx"))
+		};
+		if (hasClient) virtualRouteConfig.file = appletConfig.hasAuthorRoot ? "__root.tsx" : relative(routesDirectory, resolve(resolvedRoot, ".hitch/appletRoot.gen.tsx"));
+		return appletConfig;
+	};
+	const requireAppletConfig = () => {
+		if (appletConfig === void 0) throw new Error("Vite did not provide an applet project root.");
+		return appletConfig;
+	};
+	let apiManifest;
+	const callerRoot = resolve(".");
+	if (basename(callerRoot) === parsedDefinition.data.code && basename(resolve(callerRoot, "..")) === "applets") apiManifest = appletManifestSchema.parse({
+		org: resolveWorkspaceOrg(callerRoot),
+		...parsedDefinition.data
+	});
+	const orchestrator = {
+		name: "hitch-applet",
+		enforce: "pre",
+		sharedDuringBuild: true,
+		api: { get manifest() {
+			if (apiManifest === void 0) throw new Error("Applet manifest is not available before Vite resolves the project.");
+			return apiManifest;
+		} },
+		async config(config, environment) {
+			const { root, manifest, hasClient, hasAuthorRoot, hasServer, hasRouter } = resolveAppletConfig(config.root ?? resolve("."));
+			apiManifest = manifest;
+			buildRootOutDir = resolve(root, config.build?.outDir ?? "dist");
+			if (environment.command === "build" && !clearedOutDir) {
+				await rm(buildRootOutDir, {
+					force: true,
+					recursive: true
+				});
+				clearedOutDir = true;
+			}
+			if (environment.command === "build") themeStylesheetUrl = `${organizationInstanceUrl(await resolveInstanceUrl(void 0, options.store), manifest.org)}/theme.css`;
+			if (environment.command === "build" && manifest.objects.length > 0) {
+				contractSync ??= syncContract(resolve(root, ".hitch"), manifest, {
+					...options,
+					changesetId: (options.store?.env ?? process.env).HITCH_CHANGESET_ID
+				});
+				await contractSync;
+			}
+			const hasHitchGen = existsSync(resolve(root, ".hitch/index.ts"));
+			await Promise.all([
+				writeManifestGen(resolve(root, ".hitch"), manifest),
+				hasClient ? writeClientEntry(root, {
+					appletCode: manifest.code,
+					hasHitchGen,
+					hasRouter
+				}) : void 0,
+				hasClient && !hasAuthorRoot ? writeAppletRoot(root) : void 0,
+				hasServer ? writeServerEntry(root, hasHitchGen, manifest.code) : void 0,
+				hasHitchGen ? void 0 : writeRegisterDeclaration(resolve(root, ".hitch"))
+			]);
+			return { base: `/${manifest.code}/` };
+		},
+		configResolved(config) {
+			apiManifest = resolveAppletConfig(config.root).manifest;
+		},
+		configureServer(server) {
+			const { manifest, root } = requireAppletConfig();
+			const mount = `/${manifest.code}`;
+			const apiPrefix = `${mount}/api`;
+			server.middlewares.use((request, response, next) => {
+				const url = request.url ?? "";
+				if (url === "/_hitch/client.js" || url.startsWith("/_hitch/client.js?")) {
+					response.statusCode = 200;
+					response.setHeader("Cache-Control", "no-store");
+					response.setHeader("Content-Type", "application/javascript; charset=utf-8");
+					response.end("// PostHog is disabled in standalone applet development.\n");
+					return;
+				}
+				if (url === "/theme.css" || url.startsWith("/theme.css?")) {
+					readFile(resolve(root, ".hitch/theme.css")).then((theme) => {
+						response.statusCode = 200;
+						response.setHeader("Cache-Control", "no-cache");
+						response.setHeader("Content-Type", "text/css; charset=utf-8");
+						response.end(theme);
+					}, (error) => {
+						if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+							next();
+							return;
+						}
+						next(error);
+					});
+					return;
+				}
+				if (url === apiPrefix || url.startsWith(`${apiPrefix}/`) || url.startsWith(`${apiPrefix}?`)) request.url = url.slice(mount.length);
+				next();
+			});
+		},
+		transformIndexHtml: {
+			order: "post",
+			handler(html) {
+				const parentOrigin = themeStylesheetUrl === void 0 ? void 0 : new URL(themeStylesheetUrl).origin;
+				return {
+					html: themeStylesheetUrl === void 0 ? html : html.replace("href=\"/theme.css\"", `href="${themeStylesheetUrl}"`),
+					tags: [{
+						tag: "script",
+						attrs: {
+							async: true,
+							"vite-ignore": true,
+							src: "/_hitch/client.js"
+						},
+						injectTo: "head-prepend"
+					}, {
+						tag: "script",
+						children: clientBootstrapScript(parentOrigin, requireAppletConfig().manifest.code),
+						injectTo: "head-prepend"
+					}]
+				};
+			}
+		},
+		writeBundle: {
+			order: "post",
+			async handler(outputOptions, bundle) {
+				if (buildRootOutDir === void 0) throw new Error("Applet build output is not configured.");
+				if (this.environment.name === "client") {
+					await writeFile(resolve(buildRootOutDir, "manifest.json"), `${JSON.stringify(requireAppletConfig().manifest, null, 2)}\n`);
+					if (!requireAppletConfig().hasServer) await appendFile(resolve(buildRootOutDir, ".assetsignore"), "manifest.json\n");
+					console.log(`client → ${relative(requireAppletConfig().root, outputOptions.dir ?? buildRootOutDir)}/`);
+					return;
+				}
+				if (!requireAppletConfig().hasServer || this.environment.name !== "worker") return;
+				if (!requireAppletConfig().hasClient) await writeFile(resolve(buildRootOutDir, "manifest.json"), `${JSON.stringify(requireAppletConfig().manifest, null, 2)}\n`);
+				const workerDir = outputOptions.dir ?? resolve(buildRootOutDir, "worker");
+				const mainModule = Object.values(bundle).find((output) => output.type === "chunk" && output.isEntry)?.fileName;
+				const strayModules = (await readdir(workerDir, { recursive: true })).filter((path) => /\.(js|mjs)$/.test(path) && path !== mainModule);
+				if (strayModules.length > 0) throw new Error(`The applet server must bundle to a single worker/index.js module; found: ${strayModules.join(", ")}. Avoid dynamic import() in server code.`);
+				console.log(`server → ${relative(requireAppletConfig().root, resolve(workerDir, mainModule ?? ""))}`);
+			}
+		}
+	};
+	const cloudflarePlugins = cloudflare({
+		get assetsOnly() {
+			return !requireAppletConfig().hasServer;
+		},
+		config: (workerConfig) => {
+			const { root, manifest, hasClient, hasServer } = requireAppletConfig();
+			return {
+				...workerConfig,
+				name: manifest.code.replaceAll("_", "-"),
+				compatibility_date: APPLET_COMPATIBILITY_DATE,
+				compatibility_flags: APPLET_COMPATIBILITY_FLAGS,
+				...hasClient ? { assets: {
+					not_found_handling: "single-page-application",
+					run_worker_first: ["/api/*"]
+				} } : {},
+				...hasServer ? { main: resolve(root, ".hitch/entry.server.gen.ts") } : {}
+			};
+		},
+		get viteEnvironment() {
+			return requireAppletConfig().hasServer ? { name: "worker" } : void 0;
+		}
+	}).map((plugin) => ({
+		...plugin,
+		apply: ((_config, { mode }) => mode !== "test")
+	}));
+	return [
+		orchestrator,
+		...existsSync(resolve("src/client/routes")) ? [tanstackRouter({
+			generatedRouteTree: ".hitch/routeTree.gen.ts",
+			routesDirectory: "src/client/routes",
+			routeFileIgnorePattern: "__root",
+			virtualRouteConfig
+		}), react()] : [],
+		cloudflarePlugins
+	];
+}
+//#endregion
+export { applet };

package/dist/workflow-CTo2kZF1.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/server/identity.ts
+const requestContext = new AsyncLocalStorage();
+function runWithRequestContext(context, fn) {
+	return requestContext.run(context, fn);
+}
+function tryGetRequestContext() {
+	return requestContext.getStore();
+}
+function getRequestContext() {
+	const context = requestContext.getStore();
+	if (context === void 0) throw new Error("Hitch request context is unavailable outside a request.");
+	return context;
+}
+function getIdentityBearer(identity) {
+	return identity.kind === "user" ? identity.sessionToken : identity.token;
+}
+//#endregion
+//#region src/server/workflow.ts
+const DURATION_MULTIPLIERS = {
+	milliseconds: 1,
+	seconds: 1e3,
+	minutes: 6e4,
+	hours: 36e5,
+	days: 864e5,
+	weeks: 6048e5
+};
+const MAX_DURATION_MS = 365 * DURATION_MULTIPLIERS.days;
+const unit = z.number().nonnegative().optional();
+const workflowDurationSchema = z.strictObject({
+	milliseconds: unit,
+	seconds: unit,
+	minutes: unit,
+	hours: unit,
+	days: unit,
+	weeks: unit
+}).refine((duration) => sumMilliseconds(duration) <= MAX_DURATION_MS, "must not exceed 365 days");
+function sumMilliseconds(duration) {
+	return Object.entries(DURATION_MULTIPLIERS).reduce((total, [key, multiplier]) => total + (duration[key] ?? 0) * multiplier, 0);
+}
+function toMilliseconds(duration) {
+	const parsed = workflowDurationSchema.safeParse(duration);
+	if (!parsed.success) throw new Error(`Invalid workflow duration: ${z.prettifyError(parsed.error)}`);
+	return sumMilliseconds(parsed.data);
+}
+function createWorkflow(run) {
+	return { run };
+}
+//#endregion
+export { getRequestContext as a, getIdentityBearer as i, createWorkflow as n, runWithRequestContext as o, toMilliseconds as r, tryGetRequestContext as s, MAX_DURATION_MS as t };

package/dist/workflow-DurM6Fwx.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+//#region src/server/workflow.d.ts
+type WorkflowDuration = {
+  milliseconds?: number;
+  seconds?: number;
+  minutes?: number;
+  hours?: number;
+  days?: number;
+  weeks?: number;
+};
+type WorkflowStep = {
+  do<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+  do<T>(name: string, options: {
+    retries?: {
+      limit: number;
+      delay: WorkflowDuration;
+      backoff?: "constant" | "linear" | "exponential";
+    };
+  }, fn: () => T | Promise<T>): Promise<T>;
+  sleep(name: string, duration: WorkflowDuration): Promise<void>;
+};
+type WorkflowDefinition<Payload, Result> = {
+  readonly run: (step: WorkflowStep, payload: Payload) => Promise<Result>;
+};
+type AnyWorkflowDefinition = WorkflowDefinition<any, any>;
+declare function createWorkflow<Payload, Result>(run: (step: WorkflowStep, payload: Payload) => Promise<Result>): WorkflowDefinition<Payload, Result>;
+//#endregion
+export { createWorkflow as a, WorkflowStep as i, WorkflowDefinition as n, WorkflowDuration as r, AnyWorkflowDefinition as t };

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@hitch42/applet",
+  "version": "0.1.0-beta.2",
+  "license": "MIT",
+  "bin": {
+    "applet": "./dist/applet.js"
+  },
+  "files": [
+    "dist",
+    "scaffold"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "source": "./src/author/server.ts",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "source": "./src/author/client.ts",
+      "default": "./dist/client.js"
+    },
+    "./react": {
+      "source": "./src/react/index.ts",
+      "default": "./dist/react.js"
+    },
+    "./vite": {
+      "source": "./src/vite.ts",
+      "default": "./dist/vite.js"
+    },
+    "./_internal/client": {
+      "source": "./src/internal/client.ts",
+      "default": "./dist/_internal/client.js"
+    },
+    "./_internal/server": {
+      "source": "./src/internal/server.ts",
+      "default": "./dist/_internal/server.js"
+    }
+  },
+  "dependencies": {
+    "@cloudflare/vite-plugin": "^1.51.1",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@hey-api/openapi-ts": "0.0.0-next-20260824173136",
+    "@orpc/client": "^1.15.0",
+    "@orpc/contract": "^1.15.0",
+    "@orpc/openapi-client": "^1.15.0",
+    "@orpc/tanstack-query": "^1.15.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "@tanstack/query-async-storage-persister": "5.101.4",
+    "@tanstack/react-query-persist-client": "5.101.4",
+    "@tanstack/router-cli": "^1.167.24",
+    "@tanstack/router-plugin": "^1.168.23",
+    "@tiptap/core": "^3.30.3",
+    "@tiptap/extension-image": "^3.30.3",
+    "@tiptap/extension-list": "^3.30.3",
+    "@tiptap/extension-table": "^3.30.3",
+    "@tiptap/extensions": "^3.30.3",
+    "@tiptap/markdown": "^3.30.3",
+    "@tiptap/react": "^3.30.3",
+    "@tiptap/starter-kit": "^3.30.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "croner": "^10.0.1",
+    "lucide-react": "^1.33.0",
+    "react-aria-components": "^1.20.0",
+    "shadcn": "^4.16.1",
+    "streamdown": "^2.6.0",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.0",
+    "tw-animate-css": "^1.4.0",
+    "vite": "8.3.0",
+    "vitest": "4.1.11",
+    "wrangler": "^4.120.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@orpc/server": "^1.15.0",
+    "@tanstack/react-query": "5.101.4",
+    "@tanstack/react-router": "^1.170.18",
+    "@types/node": "^24",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hitch-42/hitch.git",
+    "directory": "packages/applet"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "beta"
+  }
+}

package/scaffold/.agents/skills/hitch-applets/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: hitch-applets
+description: Build, change, test, and debug Hitch applets. Use for applet routes, Hitch data access, applet servers, contract and theme generation, local development, deployment, and applet UI work.
+---
+
+# Hitch Applets
+
+Build small applets against an organization's Hitch data. Keep each applet focused on one related workflow.
+
+Treat each applet as an isolated microfrontend. Keep it separate from the data storage layer, and access Hitch data through the SDK.
+
+## Go deeper
+
+This file holds the common rules. Read each matching reference before you edit an applet. Paths are relative to this file.
+
+| Read this                 | When the task involves                                                                                   |
+| ------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `references/client.md`    | Client routes, navigation, page layout, forms, controls, or other user interface work                    |
+| `references/records.md`   | Listing, querying, creating, or updating records; filters, includes, aggregates; a missing record method |
+| `references/files.md`     | Uploading or reading files, attachment attributes, download links                                        |
+| `references/markdown.md`  | Rendering or editing markdown, image uploads, Hitch file links                                           |
+| `references/server.md`    | The applet server: secrets, env variables, external services, the `api` client                           |
+| `references/schedules.md` | Cron schedules and background runs                                                                       |
+| `references/workflows.md` | Multi-step server work: `createWorkflow`, `step.do`, `step.sleep`, starting, reading, and listing runs   |
+| `references/manifest.md`  | The applet definition in `applet.manifest.ts`: objects, access, variables, and packages                  |
+
+## Work with the workspace
+
+- Run package commands with `pnpm`.
+- If `package.json` is absent, read `sdk` from `hitch.config.ts`. Run `pnpm dlx <sdk> bootstrap` from the workspace root.
+- Run `pnpm exec applet new <code>` from the workspace root to create a full applet.
+- Add `--client-only` or `--server-only` when the applet needs only one part.
+- Use `--client-only` for a user interface that uses the current user's Hitch access and needs no server.
+- Use `--server-only` for an API or schedule that needs no user interface.
+- The `new` command creates the applet before it installs packages and generates Hitch types.
+- If installation or generation fails, inspect the created applet. Do not run `new` again.
+- Run `pnpm install`, then rerun `pnpm exec applet generate` from the applet directory.
+- If the user selects `--no-install`, do not run package scripts until applet dependencies are available.
+- If generation cannot select a saved login, ask the user to fix the login or provide `HITCH_API_KEY`.
+- Do not install or run a different Hitch CLI to repair applet generation.
+- Run `pnpm --dir applets/<code> run generate` after a Hitch object, operation, or theme changes.
+- Run generation at the start of a session when the task depends on current Hitch types.
+- Run `pnpm --dir applets/<code> run dev` and `pnpm --dir applets/<code> run build` from the workspace root.
+- Run `pnpm --dir applets/<code> run deploy` only when the user requests a deployment.
+- Edit only `hitch.config.ts`, `applet.manifest.ts`, and files in `src`.
+- Treat all other workspace files as generated output. The applet CLI replaces them.
+- Remember that generation refreshes the local theme copy. Deployed applets load the public org theme from its Hitch `.com` URL.
+
+## Use Vite and Vitest
+
+- Import configuration APIs from `vite`.
+- Import test APIs from `vitest`.
+- Keep Vite configuration in the generated `vite.config.ts` file.
+- Add applet packages to `dependencies` or `devDependencies` in `applet.manifest.ts`.
+
+## Access Hitch data
+
+Use the client SDK unless the task needs a secret or an external service:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+import { hitch } from "@hitch42/applet/client";
+
+const deals = useQuery(
+  hitch.records.deals.list.queryOptions({
+    input: { query: {} },
+  }),
+);
+```
+
+The client SDK uses the current user's identity and access. Do not add a server proxy for filtering or access control.
+
+Use the server SDK for secrets, external services, or imperative Hitch data access:
+
+```ts
+import { env, hitch } from "@hitch42/applet/server";
+```
+
+Define an applet server with an oRPC router:
+
+```ts
+import { os } from "@orpc/server";
+
+const router = {
+  hello: os.handler(() => ({ hello: "World!" })),
+};
+
+export default { router };
+```
+
+Call applet server procedures through the generated client API:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+import { api } from "@hitch42/applet/client";
+
+const greeting = useQuery(api.hello.queryOptions());
+```
+
+Use generated types as the source of truth. Do not add casts or local copies that bypass them.
+
+Do not invent fields or silence type errors with casts. Ask the user when generated types exclude a requested field or operation.
+
+## Work with files
+
+Upload a file with one call. The SDK creates the file record and sends the bytes directly to storage:
+
+```ts
+import { hitch } from "@hitch42/applet/client";
+
+const uploaded = await hitch.files.upload(file); // file is a web File
+```
+
+Read `references/files.md` before download links, attachment attributes, or server-side uploads.
+
+## Diagnose with logs
+
+- Add useful `console.<level>` calls around important server work and failures. Deployed logs often provide the clearest evidence for applet issues.
+- Choose `console.log`, `console.info`, `console.warn`, or `console.error` deliberately. The console method sets the entry level used by log filters.
+- Run `pnpm --dir applets/<code> exec applet logs --filter '{"type":"applet"}'` from the workspace root to inspect applet code logs.
+- Include the applet type filter during diagnosis. Without it, Cloudflare invocation entries can hide the useful applet entries.
+- Do not log secrets, tokens, or personal data.
+
+## Verify changes
+
+Run these commands from the workspace root before deployment:
+
+```sh
+pnpm --dir applets/<code> run generate
+pnpm --dir applets/<code> run typecheck
+pnpm --dir applets/<code> run test # Only when the applet contains tests.
+pnpm --dir applets/<code> run build
+```
+
+If missing packages block a check, stop package checks. Do not retry the check through another binary.
+
+If a command fails, report the exact blocker. Do not deploy as a verification step.