@hitch42/applet 0.1.1-beta.1 → 0.1.1-beta.5

package/dist/applet.js

@@ -35,6 +35,7 @@ Deploy options:
   --changeset <id>    Deploy against a pending schema changeset. The build
                       generates against its schema and the release promotes
                       when the changeset applies. Manifest mismatches warn.
+Run applet deploy in the workspace root to deploy every applet.
 
 Logs options:
   --since <duration>  Show logs from this period. Default: 1h. Maximum: 7d.
@@ -51,7 +52,9 @@ Variables options:
   --secret            Store the value as a secret.
   -y, --yes           Skip the live applet confirmation.
 
-CI: set HITCH_API_KEY (and HITCH_API_URL for a non-default instance).`;
+CI: set HITCH_API_KEY (and HITCH_API_URL for a non-default instance).
+GitHub Actions: generate, build, and deploy use the job's OIDC token instead of
+a key. Grant the job id-token: write.`;
 async function main() {
 	const { positionals, values } = parseArgs({
 		allowPositionals: true,
@@ -82,23 +85,23 @@ async function main() {
 	const noLogFlags = values.run === void 0 && values.filter === void 0 && values.level === void 0 && values.limit === void 0 && values.live === void 0 && values.search === void 0 && values.since === void 0;
 	const noModeFlags = values["client-only"] === void 0 && values["server-only"] === void 0;
 	if (positionals.length === 1 && positionals[0] === "bootstrap" && values.changeset === void 0 && noModeFlags && noGitFlags && noVariableFlags && noLogFlags) {
-		await (await import("./init-BS1Y-eNL.js")).runBootstrap({ install: values["no-install"] !== true });
+		await (await import("./init-VzV28EFT.js")).runBootstrap({ install: values["no-install"] !== true });
 		return;
 	}
 	if (positionals.length === 1 && positionals[0] === "generate" && values["no-install"] === void 0 && noModeFlags && noGitFlags && noVariableFlags && noLogFlags) {
-		await (await import("./generate-6Nbt7uii.js")).runGenerate({ changesetId: values.changeset });
+		await (await import("./generate-D5rSXXa-.js")).runGenerate({ changesetId: values.changeset });
 		return;
 	}
 	if (positionals.length === 1 && positionals[0] === "build" && values["no-install"] === void 0 && noModeFlags && noGitFlags && noVariableFlags && noLogFlags) {
-		await (await import("./build-CEku1lyb.js")).runBuild({ changesetId: values.changeset });
+		await (await import("./build-pvl3vj91.js")).runBuild({ changesetId: values.changeset });
 		return;
 	}
 	if (positionals.length === 1 && positionals[0] === "deploy" && values["no-install"] === void 0 && noModeFlags && noGitFlags && noVariableFlags && noLogFlags) {
-		await (await import("./deploy-D3BGDqgC.js")).runDeploy({ changesetId: values.changeset });
+		await (await import("./deploy-BDonkPqF.js")).runDeploy({ changesetId: values.changeset });
 		return;
 	}
 	if (positionals.length === 2 && positionals[0] === "init" && values.changeset === void 0 && noModeFlags && noVariableFlags && noLogFlags) {
-		await (await import("./init-BS1Y-eNL.js")).runInit(positionals[1], {
+		await (await import("./init-VzV28EFT.js")).runInit(positionals[1], {
 			commit: values["no-commit"] !== true,
 			git: values["no-git"] !== true,
 			install: values["no-install"] !== true
@@ -106,7 +109,7 @@ async function main() {
 		return;
 	}
 	if (positionals.length === 2 && positionals[0] === "new" && values.changeset === void 0 && noGitFlags && noVariableFlags && noLogFlags) {
-		await (await import("./init-BS1Y-eNL.js")).runNew({
+		await (await import("./init-VzV28EFT.js")).runNew({
 			code: positionals[1],
 			clientOnly: values["client-only"],
 			install: values["no-install"] !== true,

package/dist/{build-Rk3xDZV7.js → build-D1S5XCRV.js}

@@ -1,4 +1,4 @@
-import { r as prepareAppletProject } from "./project-CxN-Dtc7.js";
+import { r as prepareAppletProject } from "./project-mW0vsN8A.js";
 import { rm } from "node:fs/promises";
 import { resolve } from "node:path";
 import { spawn } from "node:child_process";
@@ -28,8 +28,7 @@ async function runPnpm(args, cwd) {
 		});
 	});
 }
-async function buildApplet(changesetId, outDir = ".hitch/dist") {
-	const appletRoot = process.cwd();
+async function buildApplet(appletRoot, changesetId, outDir = ".hitch/dist") {
 	const { workspaceRoot } = await prepareAppletProject(appletRoot);
 	await rm(resolve(appletRoot, ".hitch"), {
 		force: true,
@@ -68,7 +67,7 @@ async function buildApplet(changesetId, outDir = ".hitch/dist") {
 	});
 }
 async function runBuild(options = {}) {
-	await buildApplet(options.changesetId);
+	await buildApplet(process.cwd(), options.changesetId);
 }
 //#endregion
 export { runBuild as n, buildApplet as t };

package/dist/build-pvl3vj91.js

@@ -0,0 +1,2 @@
+import { n as runBuild } from "./build-D1S5XCRV.js";
+export { runBuild };

package/dist/ci-D0nC_Ho7.js

@@ -0,0 +1,52 @@
+import { i as resolveInstanceUrl } from "./auth-DaVK0k5R.js";
+//#region src/ci.ts
+function githubActionsContext(env = process.env) {
+	if (env.GITHUB_ACTIONS !== "true" || env.HITCH_API_KEY) return void 0;
+	const requestUrl = env.ACTIONS_ID_TOKEN_REQUEST_URL;
+	const requestToken = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+	if (!requestUrl || !requestToken) throw new Error("GitHub Actions did not provide an OIDC token. Grant the job the id-token: write permission, or set HITCH_API_KEY.");
+	return {
+		requestUrl,
+		requestToken
+	};
+}
+async function hitchResponseError(response, summary) {
+	let details = "";
+	try {
+		const body = await response.json();
+		if (body !== null && typeof body === "object") details = ["code" in body && typeof body.code === "string" ? body.code : void 0, "message" in body && typeof body.message === "string" ? body.message : void 0].filter((value) => value !== void 0).join(": ");
+	} catch {
+		details = "";
+	}
+	return /* @__PURE__ */ new Error(`${summary} (${response.status})${details ? `: ${details}` : ""}.`);
+}
+async function githubActionsToken(context, instanceUrl, fetcher) {
+	const url = new URL(context.requestUrl);
+	url.searchParams.set("audience", new URL(instanceUrl).origin);
+	const response = await fetcher(url, { headers: { Authorization: `bearer ${context.requestToken}` } });
+	if (!response.ok) throw new Error(`GitHub did not issue an OIDC token (${response.status}).`);
+	const body = await response.json();
+	if (body === null || typeof body !== "object" || !("value" in body)) throw new Error("GitHub returned an OIDC token response without a value.");
+	if (typeof body.value !== "string") throw new Error("GitHub returned an OIDC token response without a value.");
+	return body.value;
+}
+async function fetchWithGitHubActions(context, options, request) {
+	const instanceUrl = await resolveInstanceUrl(void 0, options.store);
+	return request(instanceUrl, await githubActionsToken(context, instanceUrl, options.fetch ?? globalThis.fetch));
+}
+async function loadGitHubActionsBuildInputs(context, options) {
+	const fetcher = options.fetch ?? globalThis.fetch;
+	const response = await fetchWithGitHubActions(context, options, (instanceUrl, accessToken) => fetcher(`${instanceUrl}/api/ci/v1/build-inputs`, {
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` }
+	}));
+	if (!response.ok) throw await hitchResponseError(response, "Failed to load the CI build inputs");
+	const body = await response.json();
+	if (body === null || typeof body !== "object" || !("openapi" in body) || !("theme" in body) || typeof body.theme !== "string") throw new Error("The CI build inputs must contain an openapi document and a theme string.");
+	return {
+		openapi: body.openapi,
+		theme: body.theme
+	};
+}
+//#endregion
+export { loadGitHubActionsBuildInputs as i, githubActionsContext as n, hitchResponseError as r, fetchWithGitHubActions as t };

package/dist/{deploy-D3BGDqgC.js → deploy-BDonkPqF.js}

@@ -1,6 +1,9 @@
 import { t as fetchWithOrgAuth } from "./auth-DaVK0k5R.js";
-import { t as buildApplet } from "./build-Rk3xDZV7.js";
+import { n as githubActionsContext, r as hitchResponseError, t as fetchWithGitHubActions } from "./ci-D0nC_Ho7.js";
+import { r as readWorkspaceConfig } from "./load-config-BnxocLAQ.js";
+import { t as buildApplet } from "./build-D1S5XCRV.js";
 import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
 import { readFile, readdir } from "node:fs/promises";
 import { relative, resolve, sep } from "node:path";
 import { execFile } from "node:child_process";
@@ -2355,14 +2358,17 @@ async function createBundle(distDir) {
 	body.set(bundle);
 	return body;
 }
-async function readGitInfo() {
-	const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")));
+function gitEnvironment() {
+	return Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")));
+}
+async function readGitInfo(appletRoot) {
+	const env = gitEnvironment();
 	try {
 		const [{ stdout: status }, { stdout: sha }] = await Promise.all([execFileAsync("git", ["status", "--porcelain"], {
-			cwd: process.cwd(),
+			cwd: appletRoot,
 			env
 		}), execFileAsync("git", ["rev-parse", "HEAD"], {
-			cwd: process.cwd(),
+			cwd: appletRoot,
 			env
 		})]);
 		return {
@@ -2373,26 +2379,26 @@ async function readGitInfo() {
 		return { gitDirty: false };
 	}
 }
-async function deployError(response) {
-	let details = "";
-	try {
-		const body = await response.json();
-		if (body !== null && typeof body === "object") details = ["code" in body && typeof body.code === "string" ? body.code : void 0, "message" in body && typeof body.message === "string" ? body.message : void 0].filter((value) => value !== void 0).join(": ");
-	} catch {
-		details = "";
-	}
-	return /* @__PURE__ */ new Error(`Deploy failed (${response.status})${details ? `: ${details}` : ""}.`);
+async function repositoryDirectory(appletRoot) {
+	const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], {
+		cwd: appletRoot,
+		env: gitEnvironment()
+	});
+	const directory = relative(stdout.trim(), appletRoot).split(sep).join("/") || ".";
+	if (directory === ".." || directory.startsWith("../")) throw new Error(`${appletRoot} is outside its git repository ${stdout.trim()}.`);
+	return directory;
 }
-async function runDeploy(options) {
-	if (options.dist === void 0) await buildApplet(options.changesetId);
-	const distDir = resolve(options.dist ?? ".hitch/dist");
-	const manifest = await readManifest(distDir);
-	const [bundle, git] = await Promise.all([createBundle(distDir), readGitInfo()]);
+function releaseForm(manifest, bundle) {
+	const body = new FormData();
+	body.set("manifest", manifest.raw);
+	body.set("bundle", new File([bundle], "bundle.tar.gz", { type: "application/gzip" }));
+	return body;
+}
+async function deployWithOrgAuth(appletRoot, distDir, manifest, options) {
 	const fetcher = options.fetch ?? globalThis.fetch;
-	const response = await fetchWithOrgAuth(manifest.org, options, (instanceUrl, accessToken) => {
-		const body = new FormData();
-		body.set("manifest", manifest.raw);
-		body.set("bundle", new File([bundle], "bundle.tar.gz", { type: "application/gzip" }));
+	const [bundle, git] = await Promise.all([createBundle(distDir), readGitInfo(appletRoot)]);
+	return fetchWithOrgAuth(manifest.org, options, (instanceUrl, accessToken) => {
+		const body = releaseForm(manifest, bundle);
 		body.set("gitDirty", String(git.gitDirty));
 		if (git.gitSha !== void 0) body.set("gitSha", git.gitSha);
 		if (options.changesetId !== void 0) body.set("changeset_id", options.changesetId);
@@ -2402,7 +2408,28 @@ async function runDeploy(options) {
 			body
 		});
 	});
-	if (!response.ok) throw await deployError(response);
+}
+async function deployWithGitHubActions(context, appletRoot, distDir, manifest, options) {
+	const fetcher = options.fetch ?? globalThis.fetch;
+	const [bundle, sourceDirectory] = await Promise.all([createBundle(distDir), repositoryDirectory(appletRoot)]);
+	return fetchWithGitHubActions(context, options, (instanceUrl, accessToken) => {
+		const body = releaseForm(manifest, bundle);
+		body.set("source_directory", sourceDirectory);
+		return fetcher(`${instanceUrl}/api/ci/v1/applets/${manifest.code}/releases`, {
+			method: "POST",
+			headers: { Authorization: `Bearer ${accessToken}` },
+			body
+		});
+	});
+}
+async function deployApplet(appletRoot, options) {
+	const github = githubActionsContext(options.store?.env ?? process.env);
+	if (github !== void 0 && options.changesetId !== void 0) throw new Error("A changeset deploy is not available in GitHub Actions.");
+	if (options.dist === void 0) await buildApplet(appletRoot, options.changesetId);
+	const distDir = resolve(appletRoot, options.dist ?? ".hitch/dist");
+	const manifest = await readManifest(distDir);
+	const response = github === void 0 ? await deployWithOrgAuth(appletRoot, distDir, manifest, options) : await deployWithGitHubActions(github, appletRoot, distDir, manifest, options);
+	if (!response.ok) throw await hitchResponseError(response, "Deploy failed");
 	const result = await response.json();
 	console.log(`Deployed release ${result.data.id} (${result.promoted ? "promoted" : "not promoted"}).`);
 	if (result.warnings?.length) {
@@ -2412,5 +2439,26 @@ async function runDeploy(options) {
 	if (result.unset_variables?.length) console.warn(`Warning: declared variables not set: ${result.unset_variables.join(", ")}. Set them with applet variables set.`);
 	return result;
 }
+async function workspaceAppletRoots(workspaceRoot) {
+	const appletsDir = resolve(workspaceRoot, "applets");
+	const roots = (await readdir(appletsDir, { withFileTypes: true }).catch((error) => {
+		if (isErrno(error, "ENOENT")) return [];
+		throw error;
+	})).filter((entry) => entry.isDirectory()).map((entry) => resolve(appletsDir, entry.name)).filter((root) => existsSync(resolve(root, "applet.manifest.ts"))).sort();
+	if (roots.length === 0) throw new Error(`No applets were found under ${appletsDir}.`);
+	return roots;
+}
+async function runDeploy(options) {
+	const root = process.cwd();
+	if (existsSync(resolve(root, "applet.manifest.ts"))) {
+		await deployApplet(root, options);
+		return;
+	}
+	if (readWorkspaceConfig(root) === void 0) throw new Error("Run applet deploy in an applet folder or in the workspace root.");
+	for (const appletRoot of await workspaceAppletRoots(root)) {
+		console.log(`Deploying ${relative(root, appletRoot)}...`);
+		await deployApplet(appletRoot, options);
+	}
+}
 //#endregion
 export { runDeploy };

package/dist/{generate-CH0VQmUi.js → generate-C6eAL5eo.js}

@@ -1,6 +1,7 @@
 import { i as resolveInstanceUrl, n as organizationInstanceUrl, t as fetchWithOrgAuth } from "./auth-DaVK0k5R.js";
+import { i as loadGitHubActionsBuildInputs, n as githubActionsContext } from "./ci-D0nC_Ho7.js";
 import { t as loadAppletConfig } from "./load-config-BnxocLAQ.js";
-import { r as prepareAppletProject } from "./project-CxN-Dtc7.js";
+import { r as prepareAppletProject } from "./project-mW0vsN8A.js";
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import { access, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
@@ -352,6 +353,8 @@ async function responseJson(response) {
 	}
 }
 async function loadAuthenticatedSpec(orgCode, options) {
+	const github = githubActionsContext(options.store?.env ?? process.env);
+	if (github !== void 0) return (await loadGitHubActionsBuildInputs(github, options)).openapi;
 	const fetcher = options.fetch ?? globalThis.fetch;
 	const response = await fetchWithOrgAuth(orgCode, options, (instanceUrl, accessToken) => fetcher(`${instanceUrl}/api/v1/openapi.json${options.changesetId === void 0 ? "" : `?changeset_id=${encodeURIComponent(options.changesetId)}`}`, { headers: { Authorization: `Bearer ${accessToken}` } }));
 	if (!response.ok) throw new Error(`Failed to load the organization's OpenAPI spec (${response.status}).`);
@@ -364,6 +367,20 @@ async function loadThemeStylesheet(orgCode, options) {
 	if (!response.ok) throw new Error(`Failed to load the organization's theme (${response.status}).`);
 	return response.text();
 }
+async function loadBuildInputs(orgCode, options) {
+	const github = githubActionsContext(options.store?.env ?? process.env);
+	if (github !== void 0) {
+		const inputs = await loadGitHubActionsBuildInputs(github, options);
+		return {
+			spec: inputs.openapi,
+			theme: inputs.theme
+		};
+	}
+	return {
+		spec: await loadAuthenticatedSpec(orgCode, options),
+		theme: await loadThemeStylesheet(orgCode, options)
+	};
+}
 async function generateContract(spec, outDir) {
 	await mkdir(outDir, { recursive: true });
 	const paths = spec !== null && typeof spec === "object" && "paths" in spec ? spec.paths : void 0;
@@ -432,8 +449,7 @@ async function runGenerate(options) {
 	const root = process.cwd();
 	const outDir = resolve("./.hitch");
 	const manifest = await loadAppletConfig(process.cwd());
-	const spec = await loadAuthenticatedSpec(manifest.org, options);
-	const themeStylesheet = await loadThemeStylesheet(manifest.org, options);
+	const { spec, theme: themeStylesheet } = await loadBuildInputs(manifest.org, options);
 	const stagedDir = await mkdtemp(resolve("./.hitch.tmp-"));
 	const backupDir = `${stagedDir}.backup`;
 	let staged = true;

package/dist/generate-D5rSXXa-.js

@@ -0,0 +1,2 @@
+import { n as runGenerate } from "./generate-C6eAL5eo.js";
+export { runGenerate };

package/dist/{init-BS1Y-eNL.js → init-VzV28EFT.js}

@@ -1,8 +1,8 @@
 import { a as ORG_CODE_PATTERN, i as APPLET_CODE_PATTERN } from "./manifest-DyoJ1MIL.js";
 import { i as resolveInstanceUrl, r as resolveAuthForOrg } from "./auth-DaVK0k5R.js";
-import { n as runGenerate } from "./generate-CH0VQmUi.js";
+import { n as runGenerate } from "./generate-C6eAL5eo.js";
 import { n as loadAppletSourceDefinition, r as readWorkspaceConfig } from "./load-config-BnxocLAQ.js";
-import { a as writeWorkspaceSupport, i as writeAppletSupport, n as loadCliManifest, t as assertWorkspaceCli } from "./project-CxN-Dtc7.js";
+import { a as writeWorkspaceSupport, i as writeAppletSupport, n as loadCliManifest, t as assertWorkspaceCli } from "./project-mW0vsN8A.js";
 import { access, cp, mkdir, readdir, writeFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 import { spawn } from "node:child_process";

package/dist/{project-CxN-Dtc7.js → project-mW0vsN8A.js}

@@ -122,13 +122,18 @@ allowBuilds:
   workerd: true
 minimumReleaseAge: 4320
 minimumReleaseAgeExclude:
-  - "${cli.name}"
+  - "@hitch42/*"
 `;
 }
 const GITIGNORE_START = "# BEGIN Hitch generated files";
 const GITIGNORE_END = "# END Hitch generated files";
+const SKILLS = [
+	"hitch-applets",
+	"hitch-cli",
+	"hitch-data"
+];
 const GITIGNORE = `${GITIGNORE_START}
-/.agents/skills/hitch-applets/
+${SKILLS.map((skill) => `/.agents/skills/${skill}/`).join("\n")}
 /.node-version
 /AGENTS.md
 /CLAUDE.md
@@ -169,16 +174,21 @@ async function writeWorkspaceSupport(root, config, cli) {
 	const resolvedCli = cli ?? await loadCliManifest();
 	if (resolvedCli === void 0) throw new Error("The CLI package manifest is not published.");
 	assertWorkspaceCli(config, resolvedCli);
-	const skillTarget = resolve(root, ".agents/skills/hitch-applets");
+	const deployWorkflowTarget = resolve(root, ".github/workflows/hitch.yml");
 	const agents = await readFile(new URL("../scaffold/AGENTS.md", import.meta.url), "utf8");
-	await Promise.all([mkdir(resolve(root, ".agents/skills"), { recursive: true }), rm(skillTarget, {
-		force: true,
-		recursive: true
-	})]);
 	await Promise.all([
-		cp(new URL("../scaffold/.agents/skills/hitch-applets", import.meta.url), skillTarget, { recursive: true }),
+		mkdir(resolve(root, ".agents/skills"), { recursive: true }),
+		mkdir(resolve(root, ".github/workflows"), { recursive: true }),
+		...SKILLS.map((skill) => rm(resolve(root, ".agents/skills", skill), {
+			force: true,
+			recursive: true
+		}))
+	]);
+	await Promise.all([
+		...SKILLS.map((skill) => cp(new URL(`../scaffold/.agents/skills/${skill}`, import.meta.url), resolve(root, ".agents/skills", skill), { recursive: true })),
 		writeFile(resolve(root, "package.json"), `${JSON.stringify(workspacePackage(config.org), null, 2)}\n`),
 		writeFile(resolve(root, "pnpm-workspace.yaml"), workspaceFile(resolvedCli)),
+		existsSync(deployWorkflowTarget) ? void 0 : cp(new URL("../scaffold/.github/workflows/hitch.yml", import.meta.url), deployWorkflowTarget),
 		writeFile(resolve(root, ".node-version"), "24\n"),
 		writeGitignore(root),
 		writeFile(resolve(root, "AGENTS.md"), agents)

package/dist/vite.js

@@ -1,6 +1,6 @@
 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-CH0VQmUi.js";
+import { c as writeClientEntry, i as writeRegisterDeclaration, l as writeManifestGen, r as syncContract, s as writeAppletRoot, u as writeServerEntry } from "./generate-C6eAL5eo.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";
@@ -239,7 +239,10 @@ function applet(sourceDefinition, options = {}) {
 				hasServer ? writeServerEntry(root, hasHitchGen, manifest.code) : void 0,
 				hasHitchGen ? void 0 : writeRegisterDeclaration(resolve(root, ".hitch"))
 			]);
-			return { base: `/${manifest.code}/` };
+			return {
+				base: `/${manifest.code}/`,
+				...hasServer && { environments: { worker: { build: { rollupOptions: { output: { codeSplitting: false } } } } } }
+			};
 		},
 		configResolved(config) {
 			apiManifest = resolveAppletConfig(config.root).manifest;
@@ -313,7 +316,7 @@ function applet(sourceDefinition, options = {}) {
 				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.`);
+				if (strayModules.length > 0) throw new Error(`The applet server must bundle to a single worker/index.js module; found: ${strayModules.join(", ")}.`);
 				console.log(`server → ${relative(requireAppletConfig().root, resolve(workerDir, mainModule ?? ""))}`);
 			}
 		}
@@ -350,7 +353,7 @@ function applet(sourceDefinition, options = {}) {
 			routesDirectory: "src/client/routes",
 			routeFileIgnorePattern: "__root",
 			virtualRouteConfig
-		}), react()] : [],
+		}), react({ compiler: true })] : [],
 		cloudflarePlugins
 	];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitch42/applet",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.1-beta.5",
   "license": "MIT",
   "bin": {
     "applet": "./dist/applet.js"
@@ -66,6 +66,7 @@
     "clsx": "^2.1.1",
     "croner": "^10.0.1",
     "lucide-react": "^1.33.0",
+    "oxc-transform-react": "^0.149.0",
     "react-aria-components": "^1.20.0",
     "shadcn": "^4.16.1",
     "streamdown": "^2.6.0",

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

@@ -13,16 +13,19 @@ Treat each applet as an isolated microfrontend. Keep it separate from the data s
 
 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                  |
+| 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                  |
+| `references/performance.md` | Data access design: client versus server, N+1 reads, includes, aggregates, pagination, batch writes      |
+
+For attribute types, filters, and API limits, read `../hitch-data/SKILL.md`. To inspect or change Hitch data and settings from the shell, read `../hitch-cli/SKILL.md`.
 
 ## Work with the workspace
 

package/scaffold/.agents/skills/hitch-applets/references/performance.md

@@ -0,0 +1,74 @@
+# Performance
+
+Design the data access of a screen or a job before you write it. Decide the number of requests, the page size, and the largest dataset the code can touch.
+
+## Prefer the client SDK
+
+- Read and write from the browser with the client SDK for normal user work. It uses the current user's access and needs no server.
+- Add a server procedure only when the work needs a secret, an external service, a schedule, a workflow, or fan-in of many reads into one response.
+- Do not proxy a single Hitch call through the server. The proxy adds a hop and adds nothing.
+
+## Consolidate on the server when needed
+
+- When a report or dashboard needs many Hitch reads, make one applet server request, not hundreds of browser requests. A server call started by a user request keeps that user's identity.
+- On the server, collect the pages, join the sets, and return one shaped result.
+- Cache a server result in TanStack Query with a JSON-serializable value only. Do not put `Set`, `Map`, `Date`, or class instances in the cache.
+- Version the query key when the result shape changes.
+
+## Do not write N+1 reads
+
+Never call `get` once per row of a list. Use one of these instead:
+
+- **Include.** Pass `include` on the query to hydrate owner reference and user attributes in the same page. Include a reference only when each record links to a small number of targets. Include has no cap on the number of linked records it returns.
+- **One page plus one related query.** Collect the IDs from the page, then run one `query` on the related object with `$in` on its reference attribute, for example `{ company_id: { $in: companyIds } }`. Hitch has no filter on record `id`. The related query is a page too, so pass its cursor when it can exceed 200 records.
+- **Aggregate.** Use `aggregate` for a count, sum, average, minimum, or maximum. Group by up to two dimensions. Give each aggregate its own `filter` to get several metrics in one call. Never load records to count them in JavaScript.
+- **Promise.all.** Run a known, small, independent set of requests concurrently. Do not run one request per row this way.
+
+## Filter in Hitch, not in the browser
+
+- Put every filter, sort, and search term in the query body.
+- A search box that filters the loaded page hides every record on later pages. That is not search.
+- Ordered, text-match, and sort operations need the `indexed` flag on the attribute. Read `../../hitch-data/references/limits.md`.
+
+## Page every list
+
+- Every list request returns at most 200 records. A larger `limit` is clamped to 200 with no error.
+- Show a page size or a bounded scroll area in the product, with a next-page control that passes the returned `cursor`.
+- Loop the cursor only when the code must visit the whole dataset. Name the bound in a comment, and stop at it.
+- Do not write a whole-dataset loop for a number that `aggregate` can return.
+
+## Batch writes
+
+Send many writes as one batch. A batch runs in order, in one transaction, and holds at most 100 entries.
+
+```ts
+import { hitch } from "@hitch42/applet/server";
+
+const companyId = crypto.randomUUID();
+
+await hitch.batch(
+  (tx) => {
+    tx.companies.create({ body: { id: companyId, name: "Acme" } });
+    tx.deals.create({ body: { name: "Acme renewal", company_id: companyId } });
+    tx.deals.update({ params: { id: dealId }, body: { stage: "won" } });
+    tx.deals.delete({ params: { id: staleDealId } });
+    tx.deals.updateWhere({ body: { filter: { stage: "open" }, set: { stage: "lost" } } });
+  },
+  { idempotencyKey: `import-${runId}-${chunkIndex}` },
+);
+```
+
+- Call `hitch.batch(...)` on the server. Call `hitch.batch.call(...)` on the client.
+- The `tx` calls buffer. Nothing sends until the callback resolves.
+- A failed entry rolls back the whole batch. The error names the entry index and the entry error.
+- A later entry can reference a record that an earlier entry created. Supply the record `id` as a UUID on create.
+- Pass `dryRun: true` to validate a batch with no write. The response carries `dry_run: true`.
+- Pass `idempotencyKey` on every batch that a retry can send twice. After a successful batch, the same key replays the stored response with `replayed: true`. The same key with a different body fails with HTTP 422. A failed batch or a dry run does not consume the key.
+- Chunk a large import into batches of 100. Give each chunk its own idempotency key.
+- Single `create`, `update`, and `delete` calls have no idempotency key. Use a batch when a retry must be safe.
+
+## Bound background work
+
+- Process an import, sync, or backfill in batches. Save a checkpoint after each durable batch.
+- Resume from the last checkpoint. Do not restart from the beginning.
+- Make a skipped or failed item visible in the run summary. Never convert a failure into an empty result.

package/scaffold/.agents/skills/hitch-applets/references/records.md

@@ -22,7 +22,7 @@ Use the generated Hitch contract as the typed data plane.
 - `updateWhere` sends `POST /v1/<objectCode>/update` and updates matching records.
 - `aggregate` sends `POST /v1/<objectCode>/aggregate` and calculates aggregate values.
 
-- Pass an object ID in `params.id` for `get`, `update`, and `delete`.
+- Pass a record ID in `params.id` for `get`, `update`, and `delete`.
 - Pass record fields in `body` for `create` and `update`.
 - Pass structured query data in `body` for `query`.
 
@@ -86,7 +86,7 @@ const page = await hitch.records.deals.query({
     sort: { attribute: "amount", direction: "desc" },
     limit: 50,
     cursor,
-    include: ["company"],
+    include: "company",
   },
 });
 ```
@@ -100,7 +100,8 @@ const page = await hitch.records.deals.query({
 - Use only `$not_empty` for attachment fields.
 - Use `$eq`, `$in`, `$not_empty`, `$contains`, `$starts_with`, or `$ends_with` for text fields.
 - Use `$eq`, `$in`, `$not_empty`, `$lt`, `$lte`, `$gt`, or `$gte` for ordered fields.
-- Pass `true` to `$not_empty`.
+- Use `$contains`, `$starts_with`, `$ends_with`, `$lt`, `$lte`, `$gt`, `$gte`, and `sort` only on an attribute with the `indexed` flag. Read `../../hitch-data/references/limits.md`.
+- Pass `true` to `$not_empty` for set values, or `false` for empty values.
 - Pass an array to `$in`.
 - Pass a string to `$contains`, `$starts_with`, and `$ends_with`.
 - Sort with `{ attribute, direction }`.
@@ -110,12 +111,12 @@ const page = await hitch.records.deals.query({
 - Use a positive integer for `limit`.
 - The service caps `limit` at 200 and uses 50 by default.
 - Pass the returned pagination cursor back as `cursor`.
-- Pass one attribute code or an array of attribute codes as `include`.
+- Pass `include` as one string. Use the include name, which is the code without its `_id` or `_ids` suffix. Separate several names with commas.
 
 ## Aggregate records
 
 Pass `filter`, `aggregates`, and `groupBy` in the aggregate body.
-An aggregate or group attribute can name one reference step and a target attribute, for example `company_id.industry`.
+An aggregate or group attribute can name one single-value owner reference and a target attribute, for example `company_id.industry`.
 Each aggregate can have its own `filter` with the same syntax as the top-level `filter`, including nested reference filters.
 `groupBy` accepts an array of up to two dimensions.
 The array form returns `keys` and `labels` arrays per group.

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

@@ -0,0 +1,127 @@
+---
+name: hitch-cli
+description: Use the `hitch` command line to sign in, select an organization, and read or write Hitch data and administration from the shell. Use when a task needs to inspect records, try a filter or aggregate, create test data, manage teams, grants, or capabilities, apply a changeset, or check applet access without writing applet code.
+---
+
+# Hitch CLI
+
+The `hitch` command talks to one organization on one Hitch instance. Its data and admin commands are generated from that organization's API, so the command set matches the organization's objects.
+
+`hitch` is separate from `applet`. Use `applet` to create, generate, build, and deploy applets. Use `hitch` to work with the organization's data and settings. Read the `hitch-applets` skill for `applet`.
+
+## Sign in
+
+- Run `hitch login` to sign in with the device flow. The command prints a URL and a code. Open the URL and confirm the code. Add `--no-browser` when the shell cannot open a browser.
+- Run `hitch login --api-key` to store an API key instead. The command prompts for the key. Pass `--api-key <key>` to skip the prompt.
+- Set `HITCH_API_KEY` to use a key for one shell session. It overrides every stored login. While it is set, `hitch login` and `hitch logout` refuse to run.
+- Run `hitch whoami` to print the current person, email, organization name, and organization id as JSON.
+- Run `hitch logout` to remove every stored login and cached command set.
+- Set `HITCH_API_URL` or pass `--instance <url>` to `hitch login` for an instance other than the default.
+
+## Select the organization
+
+The CLI resolves the organization in this order. The first match wins.
+
+1. `--org <code>` on any command.
+2. The workspace organization: the `hitch.org` field in the nearest `package.json`, or in the workspace root when the current directory is an applet under `applets/`.
+3. `HITCH_DEFAULT_ORG`.
+
+There is no remembered active organization. When `--org` and the workspace disagree, the command fails with `--org "x" does not match workspace organization "y"`. When several organizations are stored and none is selected, the command fails and names the three ways to choose.
+
+## Refresh the commands
+
+- Run `hitch sync` after a sign-in, after a schema change, and whenever `hitch --help` lacks an object. The command downloads the organization's API and caches the generated commands. It prints `Synced 3 objects.`
+- If the CLI prints `the cached commands ... no longer load — run hitch sync`, run `hitch sync`. Until then only the built-in commands work.
+- The `admin` commands appear only when the signed-in identity holds an admin capability. A missing `admin` command means no capability, not a broken CLI.
+
+## Read the command names
+
+Every generated command follows the API route.
+
+- Data commands: `hitch <object> <verb>`. The object is its code, for example `deals`. The verbs are `list`, `get`, `create`, `update`, `delete`, `query`, `update-where`, and `aggregate`. `hitch batch` sends a batch.
+- Admin commands: `hitch admin <route segments> <verb>`. The verb comes from the HTTP method: `list` or `get` for GET, `create` for POST, `update` for PATCH, `set` for PUT, `delete` for DELETE. For example `PUT /admin/v1/teams/{id}/members/{userId}` is `hitch admin teams members set`.
+- Every path, query, and body field becomes a flag in kebab case: `--id`, `--team-id`, `--can-read`. An object or array field takes JSON: `--filter '{"stage":"won"}'`.
+- A required field is a required flag. The CLI does not prompt for a missing value. It prints the usage error.
+- Run `hitch <object> <verb> --help` to see the flags for that organization's schema.
+- Every `delete` command asks for confirmation. Pass `--yes` to skip it. A script without a terminal must pass `--yes`.
+- A command prints its result as JSON. A list prints one item per line. A command with no result prints nothing.
+- An error prints `hitch: <message>` and exits with code 1.
+
+## Work with records
+
+Examples use an object called `deals` with attributes `amount`, `stage`, and `owner_id`. Ids are UUIDs.
+
+```sh
+hitch deals list --limit 20 --include owner
+hitch deals get --id 0192f1a2-3b4c-7d5e-8f60-123456789abc --include owner
+hitch deals create --name "Acme renewal" --amount 5000 --stage open
+hitch deals update --id 0192f1a2-3b4c-7d5e-8f60-123456789abc --stage won
+hitch deals delete --id 0192f1a2-3b4c-7d5e-8f60-123456789abc --yes
+hitch deals query --filter '{"stage":{"$in":["open","won"]}}' --sort '{"attribute":"createdAt","direction":"desc"}' --limit 50
+hitch deals update-where --filter '{"stage":"open"}' --set '{"stage":"lost"}' --expect 3
+hitch deals aggregate --aggregates '[{"op":"sum","attribute":"amount","as":"total"}]' --group-by '[{"attribute":"stage"}]'
+hitch batch --requests '[{"method":"POST","path":"/v1/deals","body":{"name":"A","stage":"open"}}]'
+```
+
+- The filter, sort, include, aggregate, and batch bodies use the same shapes as the SDK. Read the `hitch-data` skill for the rules and limits.
+- A list returns one page of at most 200 records and a cursor. Pass `--cursor <value>` for the next page.
+- Data commands act as the signed-in person with that person's grants. An API key acts as the member who made it.
+
+## Administer the organization
+
+Admin commands need the matching capability. Examples use fake ids.
+
+```sh
+hitch admin teams list
+hitch admin teams create --name Sales
+hitch admin teams members set --id <teamId> --user-id <userId>
+hitch admin capabilities list
+hitch admin capabilities grants set --capability objects:manage --team-id <teamId>
+hitch admin objects list
+hitch admin objects access list --object-id <objectId>
+hitch admin teams object-grants set --team-id <teamId> --object-id <objectId> --can-create --can-read --can-update --no-can-delete
+hitch admin teams object-grants conditions create --team-id <teamId> --object-id <objectId> --operator equals --operand current_user --path <attributeId>
+hitch admin objects default-grant set --object-id <objectId> --can-read --no-can-create --no-can-update --no-can-delete
+hitch admin applets access list --code sales_portal
+hitch admin applets grants set --code sales_portal --team-id <teamId>
+```
+
+- Object grants for a team live under `admin teams object-grants`. The default grant that every member holds lives under `admin objects default-grant`. Each has `conditions` and `attributes` subcommands.
+- Add `--delegate-attribute-id <attributeId>` to an object grant to delegate through a reference attribute.
+- `admin objects access list` shows which grantees cannot read an object. `admin applets access list` shows which grantees cannot use what an applet reads.
+
+## Change the schema
+
+Schema changes go through a changeset. The CLI names the lifecycle as state, not as actions.
+
+```sh
+hitch admin changesets create
+hitch admin objects create --name Deal --changeset-id <changesetId>
+hitch admin objects attributes create --code deals --name Amount --type currency --changeset-id <changesetId>
+hitch admin changesets blockers list --id <changesetId>
+hitch admin changesets update --id <changesetId> --status applied
+hitch admin changesets update --id <changesetId> --status abandoned
+hitch admin changesets update --id <changesetId> --adopt <otherChangesetId>
+```
+
+- A schema command without `--changeset-id` applies at once when it has no blockers. With a blocker, Hitch stages it in a new pending changeset and names it in the error.
+- Add `--dry-run` to evaluate a schema command without a change.
+- Add `--indexed` to an attribute that a query must sort or filter with ordered or text operators. Add `--is-multi` for a multi-value attribute. Pass `--type-config` and `--options` as JSON.
+- Run `blockers list` before an apply. Any blocker stops the apply with HTTP 409.
+- Run `hitch sync` after an apply, so the new objects and attributes appear as commands.
+- Run `pnpm --dir applets/<code> run generate` after an apply, so applet types match.
+
+## Fix common errors
+
+| Message                                              | Cause and fix                                                                            |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `Not logged in. Run hitch login.`                    | No stored login and no `HITCH_API_KEY`. Sign in.                                         |
+| `HITCH_API_KEY was rejected.`                        | The key in the environment is invalid or revoked. Unset it or replace it.                |
+| `API key is scoped to organization "x", not "y".`    | The key belongs to another organization. Select `x` or use another key.                  |
+| `--org "x" does not match workspace organization`    | Run the command outside the workspace, or drop `--org`.                                  |
+| `Multiple organizations are stored ...`              | Pass `--org`, set `hitch.org`, or set `HITCH_DEFAULT_ORG`.                               |
+| `the cached commands ... no longer load`             | Run `hitch sync`.                                                                        |
+| `Refusing to delete without --yes`                   | Add `--yes` in a script.                                                                 |
+| `hitch <object>` is an unknown command               | Run `hitch sync`. The object is new or the cache is stale.                               |
+| `User's teams lack the `read` grant on this object.` | The identity has no grant on that object. Ask for a team grant, or use another identity. |
+| `hitch admin` is missing                             | The identity holds no admin capability.                                                  |

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

@@ -0,0 +1,51 @@
+---
+name: hitch-data
+description: The Hitch data model and data API rules. Use when a task defines or changes objects and attributes, models a relationship, writes or validates record values, builds a filter or sort, or hits an API limit. Covers attribute types, references, required and null rules, the indexed flag, and the enforced read, write, and aggregate limits.
+---
+
+# Hitch data
+
+An organization's data lives in Hitch objects. Each object has attributes. Each record holds one value per attribute. Hitch validates, normalizes, and stores every value. Applets read and write records through the SDK and never keep a private copy.
+
+## Go deeper
+
+| Read this                  | When the task involves                                                                           |
+| -------------------------- | ------------------------------------------------------------------------------------------------ |
+| `references/attributes.md` | The behavior of one attribute type: accepted values, null and empty rules, normalization, config |
+| `references/limits.md`     | A page size, a batch size, an aggregate limit, a filter that fails, or a sort that fails         |
+
+## Objects and records
+
+- An object has a code, a name, and attributes. A record belongs to one object.
+- Every record has an `id`, a required `name`, `createdAt`, `updatedAt`, and `deletedAt`.
+- A record is JSON. Every owner attribute key is present on read. An empty attribute reads as `null`. An inverse reference face has no key.
+- A record can be created with a client-supplied UUID `id`. Use this to link records inside one batch.
+
+## Attributes
+
+- An attribute is schema, not a free JSON field. Choose a type. Hitch validates the value against the type and its configuration.
+- Types: text, rich_text, integer, decimal, currency, checkbox, date, datetime, time, domain, url, email, phone, select, reference, user, attachment.
+- A value is a non-empty value or `null`. No type accepts an empty string.
+- Cardinality is configuration. Text, select, reference, user, and attachment can be multi-value.
+- A required attribute rejects `null` and rejects an empty array.
+- Store a fixed set of values as a select, not as text. Store a link to another record as a reference, not as text or as an id in a text field. Text cannot be a group dimension, and text matching needs the `indexed` flag.
+
+## References
+
+- A reference attribute names a target object. Write the target record id.
+- A reference can expose an inverse face on the target object. The owner face stores the link. The inverse face is read-only and is absent from the record JSON.
+- One-to-many is a single reference on one side and a multi inverse on the other. Many-to-many is multi on both sides. `targetSingle` limits each target record to one link through the attribute.
+- Do not model a plain relationship as a separate join object. A reference gives typed links, link cleanup when a target is deleted, filters through either face, and access through grants. Use a join object only when the relationship needs its own fields or lifecycle.
+
+## Filters and sorting
+
+- Every attribute accepts `$eq` and `$not_empty`. Every attribute except checkbox accepts `$in`.
+- Ordered operators, text-match operators, and `sort` need the `indexed` flag on the attribute. A new attribute starts with the flag off. Ask for the flag on the attributes a query needs, not on every attribute.
+- A filter can nest through a reference, through an inverse face, and can express an anti-join with `$not`.
+- An aggregate filter does not need the flag. Sum, average, minimum, and maximum need a single-value numeric attribute. A group dimension is a checkbox, select, reference, user, or a bucketed date or datetime.
+
+## Schema changes
+
+- Every object or attribute change goes through a changeset. Hitch evaluates the change against existing records and dependent applets.
+- A change that would break existing data, such as a unique constraint with duplicates, is blocked until the data is fixed.
+- An applet release can bind to a pending changeset. The changeset apply switches the schema and promotes the release together.

package/scaffold/.agents/skills/hitch-data/references/attributes.md

@@ -0,0 +1,121 @@
+# Attribute types
+
+Hitch validates and normalizes every attribute value on write. Read this before you build a form, an import, or a write path.
+
+## Rules for every type
+
+- A value is a non-empty value or `null`. Every type rejects an empty string.
+- Send `null` to clear a value. A required attribute rejects `null` on create and on update.
+- A single-value attribute rejects an array. A multi-value attribute rejects a scalar.
+- A multi-value attribute holds an ordered array. An empty array is accepted when the attribute is not required, and reads back as `null`.
+- Only text, select, reference, user, and attachment can be multi-value. Text allows duplicate entries. The other four reject duplicates.
+- A `default` in the attribute configuration applies on create only, when the body omits the attribute.
+- An `immutable` attribute rejects a change once it holds a non-null value. A null immutable attribute can still be set once.
+- A `unique` attribute rejects a duplicate value with HTTP 409. Unique is never allowed on a multi-value attribute.
+- Every owner attribute key is present on read. An empty attribute reads as `null`. An inverse reference face has no key.
+- Every attribute accepts the `$eq` and `$not_empty` filters. Every attribute except checkbox accepts `$in`. Other operators and `sort` need the `indexed` flag. Read `limits.md`.
+
+## Text and rich text
+
+| Type      | Write                                       | Normalization | Config                                                    | Unique | Multi |
+| --------- | ------------------------------------------- | ------------- | --------------------------------------------------------- | ------ | ----- |
+| text      | Non-empty string, at most 256 characters    | None          | default, immutable, unique, minLength, maxLength, pattern | Yes    | Yes   |
+| rich_text | Non-empty string, no cap unless `maxLength` | None          | default, immutable, minLength, maxLength                  | No     | No    |
+
+- `pattern` is a JavaScript regular expression string. It is not anchored.
+- Rich text is stored and returned as written. Hitch does not sanitize or parse it. Rich text supports identity filters only and never sorts.
+
+## Numbers
+
+| Type     | Write                                                   | Read shape | Config                                      | Unique |
+| -------- | ------------------------------------------------------- | ---------- | ------------------------------------------- | ------ |
+| integer  | A JavaScript number that is a safe integer              | number     | default, immutable, unique, min, max        | Yes    |
+| decimal  | A decimal string or a number, at most 12 integer digits | string     | default, immutable, unique, min, max, scale | Yes    |
+| currency | Same as decimal, scale defaults to 2                    | string     | decimal config plus `code`                  | Yes    |
+
+- Integer rejects a numeric string on write.
+- Decimal returns a canonical string. Leading zeros are removed. With `scale`, the value is padded to exactly that many places. Without `scale`, trailing zeros are removed. Excess precision is rejected, never rounded.
+- Decimal `min` and `max` are decimal strings. `scale` is 0 to 8 for decimal and 0 to 4 for currency.
+- Currency `code` is three uppercase letters. It is metadata on the attribute, not part of the value. Hitch does no conversion.
+
+## Checkbox
+
+- Write a boolean. Hitch does not coerce strings on write.
+- Config: default, immutable. No unique, no multi.
+- Filters: `$eq` and `$not_empty` only.
+
+## Date and time
+
+| Type     | Write                              | Read shape              | Timezone              | Config                               |
+| -------- | ---------------------------------- | ----------------------- | --------------------- | ------------------------------------ |
+| date     | `YYYY-MM-DD`, a real calendar date | `YYYY-MM-DD`            | None                  | default, immutable, unique, min, max |
+| datetime | Any string `Date.parse` accepts    | ISO 8601 in UTC, `...Z` | Converted to UTC      | default, immutable, unique, min, max |
+| time     | `HH:MM` or `HH:MM:SS`, 24-hour     | `HH:MM:SS`              | None, wall clock only | default, immutable, unique           |
+
+- A datetime with an offset reads back in UTC. Store the organization timezone elsewhere when the display needs it.
+- Date `min` and `max` are `YYYY-MM-DD` strings. Datetime `min` and `max` are datetime strings. Time has no `min` or `max`.
+
+## Domain, URL, email, phone
+
+| Type   | Write                                                                           | Normalization                                                           | Config                     | Unique |
+| ------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------- | ------ |
+| domain | Host name with at least two labels, no scheme, no path                          | Trimmed, lowercased, one trailing dot removed                           | default, immutable, unique | Yes    |
+| url    | `http` or `https` URL, at most 2048 bytes                                       | Canonical WHATWG form: lowercased host, trailing slash on a bare origin | default, immutable, unique | Yes    |
+| email  | One `@`, a dot in the domain part, at most 256 characters                       | Trimmed, lowercased                                                     | default, immutable, unique | Yes    |
+| phone  | 7 to 14 digits, optional leading `+`, with space, `(`, `)`, `.`, `-` separators | Separators removed, leading `+` kept                                    | default, immutable         | No     |
+
+- Email has no deliverability check.
+- Phone has no region parsing. Hitch adds no country code. Send the full international form when the organization needs it.
+
+## Select
+
+- Write the option label, not the option id. Only an active option label matches.
+- Hitch stores the option id and returns the label.
+- A deleted option reads as `null` for a single select. It is dropped from the array for a multi select.
+- Config: default, immutable. No unique. Multi-value allowed, duplicates rejected.
+- Filters: identity operators only. Sort: allowed on a single select with `indexed`.
+
+## Reference
+
+- Write the target record UUID, or an array of UUIDs for a multi reference. The target must be a live record of the declared target object.
+- A reference has two faces. The owner face stores the link. The inverse face on the target object is read-only and is absent from the record JSON. A write to it fails with `read_only_field`.
+- `targetSingle` means each target record can be linked at most once through this attribute. A second link fails with HTTP 409 `reference_conflict`.
+- Config: none. A reference accepts no default, immutable, or unique.
+- Read: the UUID or array of UUIDs under the attribute code. With `include`, the expanded record appears under the include name, which is the code without its `_id` or `_ids` suffix. Include is one level deep.
+- Filters: identity operators on the id, plus a nested filter on the target object's attributes. Sort: never.
+
+## User
+
+- Write the user UUID. The user must be a member of the organization.
+- Config: default, immutable, unique. `default` is a UUID. Multi-value allowed, duplicates rejected.
+- Read: the UUID. With `include`, the expansion is `{ id, firstName, lastName, email }`.
+- Filters: identity operators only. Sort: never.
+
+## Attachment
+
+- Write the file id from a completed upload. An unknown id fails with `file not found`. A file with no uploaded bytes fails with `file has not arrived`. Read `../../hitch-applets/references/files.md`.
+- Config: immutable only. No default, no unique. Multi-value allowed, duplicates rejected.
+- Read: the file id. `include` does not expand attachments. Call the files API for a download link.
+- Filters: identity operators only. Sort: never.
+
+## Errors
+
+| Situation                              | Status and code                                          |
+| -------------------------------------- | -------------------------------------------------------- |
+| Value fails validation                 | 400 `invalid_field`                                      |
+| Required attribute missing on create   | 400 `invalid_field`                                      |
+| Unknown attribute code in the body     | 400 `unknown_field`                                      |
+| Write to an inverse reference face     | 400 `read_only_field`                                    |
+| Change to a set immutable value        | 400 `immutable_field`                                    |
+| Missing or blank record name           | 400 `invalid_name`                                       |
+| Client-supplied `id` already exists    | 409 `id_conflict`                                        |
+| Reference target missing               | 400 `invalid_field`                                      |
+| User not a member                      | 400 `invalid_field`                                      |
+| Unique value already used              | 409 `unique_conflict`                                    |
+| Single-target reference already linked | 409 `reference_conflict`                                 |
+| Operator not allowed for the attribute | 400 `invalid_filter`                                     |
+| Attribute cannot sort                  | 400 `invalid_sort`                                       |
+| Bad `limit`, `cursor`, or `include`    | 400 `invalid_limit`, `invalid_cursor`, `invalid_include` |
+| Bad aggregate or group                 | 400 `invalid_aggregate`, `invalid_group_by`              |
+
+Every record also has a `name`. It is a required non-empty string on create.

package/scaffold/.agents/skills/hitch-data/references/limits.md

@@ -0,0 +1,64 @@
+# Hitch limits
+
+Hitch limits the data API on purpose. The limits force good software design. No screen accidentally loads 500,000 records. No report runs one request per row. No import writes half of its rows and then fails. The limits also protect the organization: one applet or one user cannot ruin the experience for everyone else, and the cost of running the data stays sensible. When a limit stops you, the design is wrong, not the limit. Change the design: page the list, aggregate in Hitch, batch the writes, or narrow the filter.
+
+Some limits clamp with no error. Some reject the request. Design for both.
+
+## Reads
+
+A page is the unit of a read. A screen shows one page and asks for the next one. A page holds at most 200 root records. An included reference has no cap on linked records, so include only small links.
+
+| Limit                              | Value       | Past the limit                   |
+| ---------------------------------- | ----------- | -------------------------------- |
+| `limit` on `list` and `query`      | 50 default  | Clamped to 200, no error         |
+| `limit` on `list` and `query`, max | 200         | Clamped to 200, no error         |
+| Filter nesting depth               | 20          | HTTP 400                         |
+| `include` depth                    | 1           | HTTP 400 for a dotted path       |
+| `include` on an inverse reference  | Not allowed | HTTP 400                         |
+| Records per included reference     | No cap      | All linked records return        |
+| IDs in one `$in` array             | No cap      | Only 200 records return per page |
+
+## Aggregates
+
+An aggregate answers a question about many records with a small result. The caps keep the result small enough to render. A question that needs more cells is two questions.
+
+| Limit                                   | Value                                                        | Past the limit           |
+| --------------------------------------- | ------------------------------------------------------------ | ------------------------ |
+| Aggregates per call                     | 20                                                           | HTTP 400                 |
+| Group dimensions                        | 2                                                            | HTTP 400                 |
+| Multi-value group dimensions            | 1                                                            | HTTP 400                 |
+| Distinct keys per dimension, default    | 50                                                           | Clamped, no error        |
+| Distinct keys per dimension, max        | 200                                                          | Clamped to 200, no error |
+| Cells, the product of dimension limits  | 2500                                                         | HTTP 400                 |
+| Reference steps in an aggregate path    | 1                                                            | HTTP 400                 |
+| Sum, average, min, max on a multi-value | Not allowed                                                  | HTTP 400                 |
+| Group dimension type                    | checkbox, select, reference, user, bucketed date or datetime | HTTP 400                 |
+| Aggregate alias `as`                    | 64 characters                                                | HTTP 400                 |
+| Sum, average, min, max on a non-numeric | Not allowed                                                  | HTTP 400                 |
+
+## Writes
+
+A write is bounded and atomic. A batch either commits every entry or none. An `updateWhere` refuses a filter that matches more than it can hold in one page, so a loose filter cannot rewrite a whole object.
+
+| Limit                                 | Value       | Past the limit                          |
+| ------------------------------------- | ----------- | --------------------------------------- |
+| Entries per batch                     | 100         | HTTP 400 before any write               |
+| Records per `updateWhere`             | 200         | HTTP 400 `update_too_broad`, no write   |
+| `expect` on `updateWhere`             | Exact count | HTTP 409 `expectation_failed`, no write |
+| Idempotency key with a different body | Not allowed | HTTP 422 `idempotency_key_reuse`        |
+| Idempotency key retention             | 24 hours    | The key is forgotten                    |
+
+## Filters and sorting
+
+Advanced filters and sorting are opt-in per attribute. This keeps each record cheap to write, and makes the attributes a query depends on an explicit decision.
+
+- Every attribute accepts `$eq` and `$not_empty`. Every attribute except checkbox accepts `$in`.
+- Ordered operators, text-match operators, and `sort` need the `indexed` flag on the attribute. Without it the request fails with HTTP 400 and a message that starts with `Enable advanced filters and sort for`.
+- New attributes start with `indexed` off. Ask the organization admin to turn it on for the attributes a query needs. Do not ask for it on every attribute.
+- No attribute allows `sort` when it is multi-value, rich text, reference, user, or attachment.
+- An aggregate filter does not need `indexed`. Sum, average, minimum, and maximum need a single-value numeric attribute.
+
+## Grant conditions
+
+- A condition path has at most two hops.
+- A record whose condition target is empty is invisible to that grant. A `get` on it returns HTTP 404.

package/scaffold/.github/workflows/hitch.yml

@@ -0,0 +1,21 @@
+name: Deploy Hitch applets
+
+on:
+  push:
+    paths:
+      - "applets/**"
+      - ".github/workflows/hitch.yml"
+      - "hitch.config.ts"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+
+permissions: {}
+
+jobs:
+  deploy:
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    permissions:
+      contents: read
+      id-token: write
+    # Hitch verifies the called workflow's commit SHA from the OIDC token.
+    uses: hitch-42/actions/.github/workflows/deploy.yml@b03cda4a4369decfc376d87425c21bcb61bddc57

package/dist/build-CEku1lyb.js

@@ -1,2 +0,0 @@
-import { n as runBuild } from "./build-Rk3xDZV7.js";
-export { runBuild };

package/dist/generate-6Nbt7uii.js

@@ -1,2 +0,0 @@
-import { n as runGenerate } from "./generate-CH0VQmUi.js";
-export { runGenerate };