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

package/dist/workflow-engine-BOTzURKM.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+//#region src/server/workflow-protocol.ts
+const journalEntrySchema = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("step"),
+		id: z.string(),
+		name: z.string(),
+		result: z.unknown()
+	}),
+	z.object({
+		kind: z.literal("sleep"),
+		id: z.string(),
+		name: z.string(),
+		until: z.number()
+	}),
+	z.object({
+		kind: z.literal("attempt"),
+		id: z.string(),
+		name: z.string(),
+		error: z.string()
+	}),
+	z.object({
+		kind: z.literal("failed"),
+		id: z.string(),
+		name: z.string(),
+		error: z.string()
+	})
+]);
+const workflowInvocationRequestSchema = z.object({
+	payload: z.unknown(),
+	journal: z.array(journalEntrySchema)
+});
+const workflowOutcomeSchema = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("step"),
+		id: z.string(),
+		name: z.string(),
+		result: z.unknown()
+	}),
+	z.object({
+		kind: z.literal("sleep"),
+		id: z.string(),
+		name: z.string(),
+		until: z.number()
+	}),
+	z.object({
+		kind: z.literal("step_error"),
+		id: z.string(),
+		name: z.string(),
+		message: z.string(),
+		retries: z.object({
+			limit: z.number(),
+			delayMs: z.number(),
+			backoff: z.enum([
+				"constant",
+				"linear",
+				"exponential"
+			])
+		})
+	}),
+	z.object({
+		kind: z.literal("done"),
+		result: z.unknown()
+	}),
+	z.object({
+		kind: z.literal("error"),
+		message: z.string()
+	})
+]);
+//#endregion
+//#region src/server/workflow-engine.ts
+var WorkflowFailedError = class extends Error {};
+async function runWorkflowJournal(engine, invoke) {
+	const journal = [];
+	for (let index = 1;; index += 1) {
+		const outcome = await engine.invoke(`invoke ${index}`, () => invoke(journal));
+		switch (outcome.kind) {
+			case "step":
+				journal.push(outcome);
+				break;
+			case "sleep":
+				journal.push(outcome);
+				await engine.sleepUntil(`sleep ${index}`, new Date(outcome.until));
+				break;
+			case "step_error": {
+				const attempts = 1 + journal.filter((entry) => entry.kind === "attempt" && entry.id === outcome.id).length;
+				journal.push({
+					kind: "attempt",
+					id: outcome.id,
+					name: outcome.name,
+					error: outcome.message
+				});
+				if (attempts > outcome.retries.limit) {
+					journal.push({
+						kind: "failed",
+						id: outcome.id,
+						name: outcome.name,
+						error: outcome.message
+					});
+					break;
+				}
+				await engine.sleep(`retry ${index}`, outcome.retries.delayMs * (outcome.retries.backoff === "exponential" ? 2 ** (attempts - 1) : outcome.retries.backoff === "linear" ? attempts : 1));
+				break;
+			}
+			case "done": return outcome.result;
+			case "error": throw new WorkflowFailedError(outcome.message);
+		}
+	}
+}
+//#endregion
+export { workflowOutcomeSchema as a, workflowInvocationRequestSchema as i, runWorkflowJournal as n, journalEntrySchema as r, WorkflowFailedError as t };

package/dist/{auth-DaVK0k5R.js → workspace-D0dnnlxL.js}

@@ -1,5 +1,7 @@
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 //#region ../shared/auth/src/store.mts
@@ -43,8 +45,8 @@ async function healCredentialStore(credentialsPath, source, store, unrecognizedC
 	console.error(unrecognizedCount === void 0 ? `hitch: reset unreadable credentials file (backup: ${backupPath}).` : unrecognizedCount === 0 ? `hitch: migrated credentials to per-organization storage (backup: ${backupPath}).` : `hitch: removed ${unrecognizedCount} unrecognized credential ${unrecognizedCount === 1 ? "entry" : "entries"} (backup: ${backupPath}).`);
 	return store;
 }
-async function readRawCredentialStore(options = {}) {
-	const { credentialsPath } = storePaths(options);
+async function readRawCredentialStore() {
+	const { credentialsPath } = storePaths();
 	let source;
 	try {
 		source = await readFile(credentialsPath, "utf8");
@@ -111,9 +113,9 @@ function organizationInstanceUrl(instanceUrl, orgCode) {
 	url.hostname = [orgCode, ...labels.slice(1)].join(".");
 	return url.toString().replace(/\/$/, "");
 }
-function storePaths(options = {}) {
-	const env = options.env ?? process.env;
-	const home = options.homeDir ?? homedir();
+function storePaths() {
+	const env = process.env;
+	const home = homedir();
 	const configDir = join(env.XDG_CONFIG_HOME || join(home, ".config"), "hitch");
 	return {
 		configDir,
@@ -122,28 +124,28 @@ function storePaths(options = {}) {
 		credentialsPath: join(configDir, "credentials.json")
 	};
 }
-async function resolveInstanceUrl(override, options = {}) {
+async function resolveInstanceUrl(override) {
 	if (override !== void 0) return normalizeInstanceUrl(override);
-	const envInstanceUrl = (options.env ?? process.env).HITCH_API_URL;
+	const envInstanceUrl = process.env.HITCH_API_URL;
 	if (envInstanceUrl !== void 0 && envInstanceUrl.length > 0) return normalizeInstanceUrl(envInstanceUrl);
-	const { configPath } = storePaths(options);
+	const { configPath } = storePaths();
 	const config = await readJson(configPath);
 	if (config === void 0) return DEFAULT_INSTANCE_URL;
 	if (!isObject(config) || config.instanceUrl !== void 0 && typeof config.instanceUrl !== "string") throw new Error(`${configPath}: expected { instanceUrl?: string }.`);
 	return normalizeInstanceUrl(config.instanceUrl ?? "https://app.hitch42.com");
 }
-async function readCredentialStore(options = {}) {
-	const store = await readRawCredentialStore(options);
+async function readCredentialStore() {
+	const store = await readRawCredentialStore();
 	return { instances: Object.fromEntries(Object.entries(store.instances).map(([instanceUrl, credentialsByOrg]) => [instanceUrl, Object.fromEntries(Object.entries(credentialsByOrg).flatMap(([orgCode, value]) => {
 		const credentials = parseCredentials(value);
 		return credentials === void 0 ? [] : [[orgCode, credentials]];
 	}))])) };
 }
-async function getCredentialsForOrg(instanceUrl, orgCode, options = {}) {
-	return (await readCredentialStore(options)).instances[normalizeInstanceUrl(instanceUrl)]?.[orgCode];
+async function getCredentialsForOrg(instanceUrl, orgCode) {
+	return (await readCredentialStore()).instances[normalizeInstanceUrl(instanceUrl)]?.[orgCode];
 }
-function environmentAuth(options) {
-	const apiKey = (options.env ?? process.env).HITCH_API_KEY;
+function environmentAuth() {
+	const apiKey = process.env.HITCH_API_KEY;
 	return apiKey !== void 0 && apiKey.length > 0 ? {
 		accessToken: apiKey,
 		source: "environment"
@@ -167,11 +169,11 @@ function resolveStoredAuthForOrg(credentialsByOrg, orgCode) {
 	const apiKeyOrgs = Object.values(credentialsByOrg).filter((credentials) => credentials.type === "apiKey").map(({ orgCode: storedOrg }) => storedOrg).sort();
 	if (apiKeyOrgs.length > 0) throw new AuthenticationError(`Stored API ${apiKeyOrgs.length === 1 ? "key is" : "keys are"} scoped to ${apiKeyOrgs.map((storedOrg) => `"${storedOrg}"`).join(", ")}, not "${orgCode}".`);
 }
-async function resolveAuthForOrg(instanceUrl, orgCode, options = {}) {
-	const auth = environmentAuth(options);
+async function resolveAuthForOrg(instanceUrl, orgCode) {
+	const auth = environmentAuth();
 	if (auth !== void 0) return auth;
 	const normalizedUrl = normalizeInstanceUrl(instanceUrl);
-	const credentialsByOrg = Object.entries((await readCredentialStore(options)).instances).find(([instance]) => instance === normalizedUrl)?.[1];
+	const credentialsByOrg = Object.entries((await readCredentialStore()).instances).find(([instance]) => instance === normalizedUrl)?.[1];
 	return resolveStoredAuthForOrg(credentialsByOrg ?? {}, orgCode);
 }
 function rejectEnvironmentKey(response, auth) {
@@ -180,9 +182,9 @@ function rejectEnvironmentKey(response, auth) {
 function bearerToken(credentials) {
 	return "apiKey" in credentials ? credentials.apiKey : credentials.accessToken;
 }
-async function setCredentials(instanceUrl, credentials, options = {}) {
-	const paths = storePaths(options);
-	const store = await readRawCredentialStore(options);
+async function setCredentials(instanceUrl, credentials) {
+	const paths = storePaths();
+	const store = await readRawCredentialStore();
 	const normalizedUrl = normalizeInstanceUrl(instanceUrl);
 	const credentialsByOrg = store.instances[normalizedUrl];
 	store.instances[normalizedUrl] = {
@@ -289,17 +291,17 @@ async function pollForToken(fetcher, instanceUrl, device, now, sleep) {
 	throw new AuthenticationError("The sign-in request expired. Run hitch login again.");
 }
 async function loginWithDevice(instanceUrl, options = {}) {
-	const fetcher = options.fetch ?? globalThis.fetch;
-	const now = options.now ?? Date.now;
+	const fetcher = globalThis.fetch;
+	const now = Date.now;
 	const { body, response } = await postJson(fetcher, `${instanceUrl}/api/auth/device/code`, { client_id: CLIENT_ID });
 	if (!response.ok) throw new AuthenticationError(typeof body.error_description === "string" ? body.error_description : `Could not start sign-in (${response.status}).`);
 	const device = parseDeviceCode(body);
 	const verificationUrl = options.expectedOrg === void 0 ? device.verification_uri_complete : `${device.verification_uri_complete}&org=${encodeURIComponent(options.expectedOrg)}`;
-	(options.print ?? console.log)(`Open ${verificationUrl} and confirm code ${device.user_code}.`);
+	console.log(`Open ${verificationUrl} and confirm code ${device.user_code}.`);
 	if (!options.noBrowser) try {
-		await (options.openUrl ?? defaultOpenUrl)(verificationUrl);
+		defaultOpenUrl(verificationUrl);
 	} catch {}
-	const token = await pollForToken(fetcher, instanceUrl, device, now, options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))));
+	const token = await pollForToken(fetcher, instanceUrl, device, now, (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
 	const { body: organizationBody, response: organizationResponse } = await postJson(fetcher, `${instanceUrl}/api/auth/device/organization`, { device_code: device.device_code });
 	if (!organizationResponse.ok) throw new AuthenticationError("The sign-in did not resolve an organization.");
 	const organization = parseDeviceOrganization(organizationBody);
@@ -317,7 +319,7 @@ async function loginWithDevice(instanceUrl, options = {}) {
 		organizationId: organization.organizationId,
 		orgCode: organization.orgCode
 	};
-	await setCredentials(instanceUrl, credentials, options.store);
+	await setCredentials(instanceUrl, credentials);
 	if (options.expectedOrg !== void 0 && organization.orgCode !== options.expectedOrg) throw new AuthenticationError(`logged in to "${organization.orgCode}" but this applet targets "${options.expectedOrg}" — confirm the right organization on the device page`);
 	return {
 		credentials,
@@ -326,25 +328,58 @@ async function loginWithDevice(instanceUrl, options = {}) {
 	};
 }
 //#endregion
+//#region ../shared/auth/src/workspace.mts
+const ORG_CODE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const require = createRequire(import.meta.url);
+function readWorkspaceConfig(dir) {
+	const path = resolve(dir, "hitch.config.ts");
+	if (!existsSync(path)) return void 0;
+	let module;
+	try {
+		module = require(path);
+	} catch (error) {
+		throw new Error(`Failed to load ${path}.`, { cause: error });
+	}
+	const config = module !== null && typeof module === "object" && "default" in module ? module.default : module;
+	if (config === null || typeof config !== "object" || !("sdk" in config) || typeof config.sdk !== "string" || config.sdk.length === 0 || !("org" in config) || typeof config.org !== "string" || !ORG_CODE_PATTERN.test(config.org)) throw new Error(`Invalid Hitch config in ${path}: "sdk" must be a package spec and "org" an organization code.`);
+	const githubWorkflow = "githubWorkflow" in config ? config.githubWorkflow : void 0;
+	if (githubWorkflow !== void 0 && typeof githubWorkflow !== "boolean") throw new Error(`Invalid Hitch config in ${path}: "githubWorkflow" must be a boolean.`);
+	return {
+		sdk: config.sdk,
+		org: config.org,
+		githubWorkflow
+	};
+}
+function findWorkspaceConfig(cwd) {
+	const appletsDir = dirname(cwd);
+	return readWorkspaceConfig(cwd) ?? (basename(appletsDir) === "applets" ? readWorkspaceConfig(dirname(appletsDir)) : void 0);
+}
+//#endregion
 //#region src/auth.ts
-async function fetchWithOrgAuth(orgCode, options, request) {
-	const fetcher = options.fetch ?? globalThis.fetch;
-	const instanceUrl = await resolveInstanceUrl(void 0, options.store);
+async function fetchWithOrgAuth(orgCode, request) {
+	const instanceUrl = await resolveInstanceUrl();
 	const organizationUrl = organizationInstanceUrl(instanceUrl, orgCode);
-	const auth = await resolveAuthForOrg(instanceUrl, orgCode, options.store);
+	const auth = await resolveAuthForOrg(instanceUrl, orgCode);
 	if (auth !== void 0) {
 		const response = await request(organizationUrl, bearerToken(auth));
-		if (response.status !== 401 && response.status !== 403) return response;
+		rejectEnvironmentKey(response, auth);
+		if (response.status !== 401) return response;
 	}
-	if (!(options.stdinIsTTY ?? process.stdin.isTTY === true)) throw new Error("not logged in — set HITCH_API_KEY or run in a terminal to log in");
-	await (options.login ?? loginWithDevice)(instanceUrl, {
-		expectedOrg: orgCode,
-		fetch: fetcher,
-		store: options.store
-	});
-	const credentials = await getCredentialsForOrg(instanceUrl, orgCode, options.store);
+	if (process.stdin.isTTY !== true) throw new AuthenticationError("Not logged in. Run applet login, or set HITCH_API_KEY.");
+	await loginWithDevice(instanceUrl, { expectedOrg: orgCode });
+	const credentials = await getCredentialsForOrg(instanceUrl, orgCode);
 	if (credentials === void 0) throw new Error(`login did not provide credentials for organization "${orgCode}"`);
 	return request(organizationUrl, bearerToken(credentials));
 }
 //#endregion
-export { resolveInstanceUrl as i, organizationInstanceUrl as n, resolveAuthForOrg as r, fetchWithOrgAuth as t };
+//#region src/workspace.ts
+function resolveWorkspaceOrg(appletRoot) {
+	const appletsDir = dirname(appletRoot);
+	if (basename(appletsDir) === "applets") {
+		const config = readWorkspaceConfig(dirname(appletsDir));
+		if (config !== void 0) return config.org;
+	}
+	throw new Error(`No Hitch workspace found for ${appletRoot}. An applet must live at <workspace>/applets/<code> with hitch.config.ts in the workspace root.`);
+}
+//#endregion
+export { loginWithDevice as a, bearerToken as c, resolveAuthForOrg as d, resolveInstanceUrl as f, readWorkspaceConfig as i, organizationInstanceUrl as l, fetchWithOrgAuth as n, AuthenticationError as o, findWorkspaceConfig as r, DEFAULT_INSTANCE_URL as s, resolveWorkspaceOrg as t, rejectEnvironmentKey as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitch42/applet",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.1-beta.10",
   "license": "MIT",
   "bin": {
     "applet": "./dist/applet.js"
@@ -27,6 +27,10 @@
       "source": "./src/react/index.ts",
       "default": "./dist/react.js"
     },
+    "./telephony": {
+      "source": "./src/telephony/index.ts",
+      "default": "./dist/telephony.js"
+    },
     "./vite": {
       "source": "./src/vite.ts",
       "default": "./dist/vite.js"
@@ -38,10 +42,15 @@
     "./_internal/server": {
       "source": "./src/internal/server.ts",
       "default": "./dist/_internal/server.js"
+    },
+    "./_internal/log-context": {
+      "source": "./src/server/log-context.ts",
+      "default": "./dist/_internal/log-context.js"
     }
   },
   "dependencies": {
     "@cloudflare/vite-plugin": "^1.51.1",
+    "@fontsource-variable/geist-mono": "^5.3.0",
     "@fontsource-variable/inter": "^5.3.0",
     "@hey-api/openapi-ts": "0.0.0-next-20260824173136",
     "@orpc/client": "^1.15.0",
@@ -49,32 +58,36 @@
     "@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",
+    "@telnyx/webrtc": "^2.27.10",
     "@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/pm": "^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",
+    "cn": "^0.4.0",
     "croner": "^10.0.1",
     "lucide-react": "^1.33.0",
+    "oxc-transform-react": "^0.149.0",
+    "oxfmt": "^0.72.0",
+    "oxlint": "^1.87.0",
+    "oxlint-tsgolint": "^7.0.2003",
     "react-aria-components": "^1.20.0",
     "shadcn": "^4.16.1",
+    "smol-toml": "^1.9.0",
     "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": {
@@ -99,6 +112,6 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org",
-    "tag": "beta"
+    "tag": "latest"
   }
 }

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

@@ -13,21 +13,31 @@ 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/email-tracking.md` | Creating pixels and reading raw email hits                                                               |
+| `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`.
+
+Read `../tanstack-router/SKILL.md` for route work and `../tanstack-query/SKILL.md` for query and cache work.
+Read `../react-best-practices/SKILL.md` for React performance and `../web-design-guidelines/SKILL.md` for requested interface reviews.
+Follow the Hitch applet rules for SDK-owned configuration, providers, and generated files.
 
 ## 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 login` from the workspace root or an applet directory to sign in. It uses the organization in `hitch.config.ts` and shares credentials with `hitch login`. Add `--no-browser` to print the sign-in URL without opening a browser.
+- A server permission error is not a login request.
+- After a workspace is linked to a repository, deploy in two ways. Run `pnpm exec applet deploy` to release a change immediately. Push to the production branch to deploy through CI and keep releases in sync with the repository.
 - 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.
@@ -41,16 +51,22 @@ This file holds the common rules. Read each matching reference before you edit a
 - 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.
+- The dev server runs as you in the production org. Reads and writes use real data.
+- The dev server prints a preview link. Open the link to see the local applet inside Hitch.
+- Chrome asks once to allow local network access for the Hitch site.
+- The preview lasts until you select Exit or close the tab.
+- A pending `requiresChangeset` schema is not available in dev. Deploy to test it.
 - 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.
+- The CLI creates missing MCP files and adds missing Hitch and Chrome DevTools entries. Existing entries and other settings belong to the user.
+- The applet CLI replaces its generated support files. It creates `.github/workflows/hitch.yml` only when the file is absent. To stop it, set `githubWorkflow: false` in `hitch.config.ts` and delete the file.
 - 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.
+- Put tests in the applet's `test` folder and name them `*.test.ts` or `*.test.tsx`. Vitest does not run test files in other folders.
+- Do not edit `vite.config.ts`. The applet CLI rewrites it. Do not add another Vite config.
 - Add applet packages to `dependencies` or `devDependencies` in `applet.manifest.ts`.
 
 ## Access Hitch data
@@ -118,9 +134,28 @@ Read `references/files.md` before download links, attachment attributes, or serv
 - 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.
+- Include the applet type filter during diagnosis. Without it, Cloudflare invocation entries can hide the useful applet entries. For a workflow run, use `--run <id>` or `--filter '{"type":"workflow"}'` instead.
 - Do not log secrets, tokens, or personal data.
 
+## Add request context with `log.set()`
+
+Each server request gets one request entry with the route, status, outcome, CPU time, and wall time. Add facts about the request to that entry:
+
+```ts
+import { log } from "@hitch42/applet/server";
+
+log.set({ invoiceId, processedCount });
+```
+
+- Set the IDs, counts, and decisions that explain what the request did. One entry with many fields is easier to filter than many `console.log` lines.
+- A later call replaces an earlier value with the same top-level key.
+- To fail a request, throw. The request entry records the error and its stack.
+- To record a problem that the code recovered from, set a field, for example `log.set({ fallbackUsed: true })`.
+- Use `console.<level>` for a separate line with its own level.
+- Outside a request, for example at module scope, `log.set()` warns and drops the fields.
+- A single call larger than 16 KB is dropped. The entry then shows `noteDropped`.
+- Run `pnpm --dir applets/<code> exec applet logs --filter '{"type":"invocation"}'` to read request entries. The CLI prints the fields and any error stack.
+
 ## Verify changes
 
 Run these commands from the workspace root before deployment:
@@ -128,6 +163,8 @@ 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 fmt
+pnpm --dir applets/<code> run lint
 pnpm --dir applets/<code> run test # Only when the applet contains tests.
 pnpm --dir applets/<code> run build
 ```
@@ -135,3 +172,11 @@ 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.
+
+## Deploy from GitHub
+
+- A push to the production branch runs `applet deploy` in the workspace root through GitHub Actions.
+- An applet deploys when its folder or a file outside `applets/` differs from its current release, including a local `applet deploy`. Uncommitted and untracked files count. Gitignored files do not count. An applet whose current release has no source hash always deploys.
+- The deploy skips other applets and logs the reason. A skip is expected, not a failure.
+- A schema change in Hitch alone does not trigger CI.
+- Do not import from a sibling applet folder. The change check does not follow such imports.

package/scaffold/.agents/skills/hitch-applets/references/email-tracking.md

@@ -0,0 +1,49 @@
+# Email tracking
+
+Create one pixel for each email. Put its URL in the HTML before send.
+Add the pixel next to CID images. A CID image cannot make a tracking request.
+
+```ts
+const { id, url } = await hitch.email.tracking.createPixel({
+  tags: { campaignId: "fall", buyerId: "acme", version: "v2" },
+});
+const html = `<p>Hello</p><img src="${url}" width="1" height="1" alt="">`;
+// Send the email with the applet's email provider.
+await hitch.email.tracking.markSent({ id });
+```
+
+`markSent({ id, sentAt })` accepts an ISO time. A later call replaces the sent time.
+`get({ id })` returns one tracker. `list()` returns up to 100 trackers by default.
+Use `filter`, `sentAt`, `cursor`, and `limit` to select a page.
+
+```ts
+const tracker = await hitch.email.tracking.get({ id });
+const query = {
+  filter: { buyerId: "acme" },
+  sentAt: { $gte: "2026-10-01T00:00:00Z" },
+  limit: 100,
+};
+const page = await hitch.email.tracking.list(query);
+const next = page.nextCursor
+  ? await hitch.email.tracking.list({ ...query, cursor: page.nextCursor })
+  : null;
+const opened =
+  tracker.lastHitAt !== null &&
+  new Date(tracker.lastHitAt).getTime() >
+    new Date(tracker.sentAt ?? tracker.createdAt).getTime() + 60_000;
+```
+
+The example rule counts a tracker as opened when `lastHitAt` is more than 60 seconds after send or creation.
+Hitch records `firstHitAt` and `lastHitAt`. It does not classify opens.
+Each page must repeat the same filter, `sentAt`, and limit.
+
+Tags stay fixed after creation. Use at most 10 tags. A key starts with an ASCII letter.
+The rest contains ASCII letters, digits, or underscores, up to 64 characters total.
+Each value has 1 to 200 characters. A filter matches every tag by exact equality.
+Everyone with applet access sees all its trackers.
+
+Gmail can fetch through `GoogleImageProxy` a few seconds after send.
+A real Gmail open has the same user agent. A Gmail draft preview can fetch before send.
+Apple Mail Privacy Protection fetches on delivery with `Mozilla/5.0`.
+That fetch looks like a real open. Proton fetches on delivery.
+Clients with images off never fetch the pixel.

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

@@ -67,7 +67,7 @@ Use `download` when a component needs one fresh link without query state:
 
 ```ts
 const file = await hitch.files.download(id);
-file.downloadUrl; // a download link, valid for one hour
+file.downloadUrl; // a download link, valid for at least a day
 ```
 
 Use the `get` query utilities when React needs file metadata as query state.
@@ -86,11 +86,11 @@ if (fileQuery.data) {
   row.filename; // "report.csv"
   row.contentType; // "text/csv"
   row.sizeBytes; // 1024
-  downloadUrl; // a download link, valid for one hour
+  downloadUrl; // a download link, valid for at least a day
 }
 ```
 
-A `downloadUrl` expires after one hour. Call `get` again for a fresh link instead of storing one.
+A `downloadUrl` expires after 24 to 48 hours. Call `get` again for a fresh link instead of storing one.
 
 ## Link a file to a record
 

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

@@ -11,6 +11,7 @@ The applet tool reads `org` from `hitch.config.ts` in the workspace root.
 - `name` gives the applet a display name.
 - `code` gives the applet its stable code and URL prefix.
 - `objects` declares record objects and attribute access.
+- `requiresChangeset` optionally names the schema changeset that the code needs.
 - `variables` optionally declares runtime variables.
 - `schedules` optionally declares scheduled server calls.
 - `dependencies` optionally declares applet runtime packages.
@@ -42,6 +43,22 @@ The manifest and applet definition reject unknown fields.
 - Expect the Vite base path to be `/<code>/`.
 - Include the code in each client route path.
 
+## Set `requiresChangeset`
+
+Set `requiresChangeset` when the code needs a schema change that is not live yet.
+
+```ts
+requiresChangeset: "0192a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
+```
+
+- Use the ID of a changeset in the same organization.
+- Generate, build, and deploy all use this field. The CLI has no changeset flag.
+- While the changeset is pending, types and the build use the schema that the changeset will produce.
+- While the changeset is pending, a deploy binds the release to the changeset. The release goes live when a person applies the changeset in Hitch.
+- After the changeset applies, the field uses the live schema. A deploy then promotes as usual. Remove the field when it is convenient.
+- A deploy fails when the changeset was abandoned. Remove the field or name a pending changeset.
+- A git push uses the same rules. The push never applies the changeset.
+
 ## Declare objects
 
 Add one entry for each object that the applet needs.
@@ -66,6 +83,14 @@ Each object entry has five required fields.
 - `readOnly` lists attribute codes that the applet can read but cannot write.
 - `readWrite` lists attribute codes that the applet can read and write.
 
+Set `optional: true` when the applet works for a viewer without access to this object.
+List codes from `readOnly` or `readWrite` in `optionalAttributes` when some viewers cannot see their values.
+Typegen makes these record fields nullable for every viewer.
+These fields never grant or remove access.
+They matter when an org shares the applet with a connected organisation.
+Hitch refuses a share if the connected org lacks access to a required object.
+Hitch also refuses a share if a required object lists a required user attribute outside `optionalAttributes`.
+
 - Use the applet code format for each object code.
 - Do not declare the same object code more than once.
 - Use the applet code format for each attribute code.
@@ -75,14 +100,16 @@ Each object entry has five required fields.
 
 The object declaration caps record access for the applet identity.
 
-- Declare only the objects that scheduled applet work needs.
-- Declare only the attributes that scheduled applet work needs.
+- Declare only the objects that the applet uses.
+- Declare only the attributes that the applet uses.
+- The declaration sets both the generated contract and the applet identity's cap.
 - Use `readOnly` for attributes that the applet identity must not change.
 - Use `readWrite` for attributes that the applet identity can change.
 - Set `canCreate` and `canDelete` to the required values.
 - The generated contract omits undeclared objects.
 - The generated contract removes `create` when `canCreate` is false.
 - The generated contract removes `delete` when `canDelete` is false.
+- The generated contract removes `update` and `updateWhere` when `readWrite` is empty.
 - Regenerate after an object grant changes.
 - Do not restore a removed object or method with a cast.