@hitch42/applet 0.1.0-beta.3 → 0.1.0-beta.9

package/dist/{auth-DaVK0k5R.js → workspace-XVtM12ZC.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
@@ -326,6 +328,33 @@ 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;
@@ -334,9 +363,10 @@ async function fetchWithOrgAuth(orgCode, options, request) {
 	const auth = await resolveAuthForOrg(instanceUrl, orgCode, options.store);
 	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");
+	if (!(options.stdinIsTTY ?? process.stdin.isTTY === true)) throw new AuthenticationError("Not logged in. Run applet login, or set HITCH_API_KEY.");
 	await (options.login ?? loginWithDevice)(instanceUrl, {
 		expectedOrg: orgCode,
 		fetch: fetcher,
@@ -347,4 +377,14 @@ async function fetchWithOrgAuth(orgCode, options, request) {
 	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, organizationInstanceUrl as c, resolveInstanceUrl as d, readWorkspaceConfig as i, rejectEnvironmentKey as l, fetchWithOrgAuth as n, AuthenticationError as o, findWorkspaceConfig as r, bearerToken as s, resolveWorkspaceOrg as t, resolveAuthForOrg as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitch42/applet",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.9",
   "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"
@@ -53,6 +57,7 @@
     "@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",

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

@@ -13,21 +13,27 @@ 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`.
 
 ## 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 +47,21 @@ 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.
+- Edit only `hitch.config.ts`, `applet.manifest.ts`, files in `src`, and `.gitignore` rules below the generated block.
+- Treat all other workspace files as generated output. The applet CLI replaces them. 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.
+- 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,7 +129,7 @@ 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.
 
 ## Verify changes
@@ -135,3 +146,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 own folder changed since its current CI release. Every applet deploys when a file outside `applets/` changed. An applet without a CI release always deploys. An applet also deploys when CI cannot load the commit of its current release.
+- 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.
@@ -75,14 +92,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.
 

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 `next_cursor` as `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

@@ -16,13 +16,14 @@ Use the generated Hitch contract as the typed data plane.
 - `list` sends `GET /v1/<objectCode>` and lists records with query parameters.
 - `create` sends `POST /v1/<objectCode>` and creates one record.
 - `get` sends `GET /v1/<objectCode>/{id}` and gets one record.
+- `history` sends `GET /v1/<objectCode>/{id}/history` and gets record changes.
 - `update` sends `PATCH /v1/<objectCode>/{id}` and updates one record.
 - `delete` sends `DELETE /v1/<objectCode>/{id}` and deletes one record.
 - `query` sends `POST /v1/<objectCode>/query` and lists records with a structured body.
 - `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`, `history`, `update`, and `delete`.
 - Pass record fields in `body` for `create` and `update`.
 - Pass structured query data in `body` for `query`.
 
@@ -73,6 +74,25 @@ const deal = await hitch.records.deals.get({
 - Do not use `.queryOptions(...)` or `.mutationOptions(...)` on the server.
 - Use the server SDK for imperative data access, secrets, or external services.
 
+## Read history
+
+```ts
+const page = await hitch.records.deals.history({
+  params: { id },
+  query: { limit: 25, cursor },
+});
+
+for (const entry of page.data) {
+  for (const change of entry.changes) {
+    if (change.attributeCode === "stage") console.log(change.to);
+  }
+}
+```
+
+You can read record history if and only if you can read the record.
+The history uses the current schema. `attributeId` tracks an attribute across renames. `attributeCode` is its current code. Older history cannot follow a rename, so some changes do not appear.
+Use `next_cursor` as the next `cursor`.
+
 ## Build a query
 
 The `query` body accepts `filter`, `sort`, `limit`, `cursor`, and `include`.
@@ -86,7 +106,7 @@ const page = await hitch.records.deals.query({
     sort: { attribute: "amount", direction: "desc" },
     limit: 50,
     cursor,
-    include: ["company"],
+    include: "company",
   },
 });
 ```
@@ -97,25 +117,26 @@ const page = await hitch.records.deals.query({
 - Use a direct field value as shorthand for `$eq`.
 - Use `$eq`, `$in`, or `$not_empty` for identity fields.
 - Use `$eq` or `$not_empty` for checkbox fields.
-- Use only `$not_empty` for attachment fields.
+- Use `$eq`, `$in`, or `$not_empty` for attachment fields. Pass file IDs.
 - 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 }`.
 - Use `asc` or `desc` as the sort direction.
-- Do not sort by multi-value, reference, user, or attachment attributes.
+- Do not sort by multi-value, reference, user, attachment, or rich text attributes.
 - Omit `sort` to sort by `createdAt` in descending order.
 - 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 the returned `next_cursor` back as `cursor`. A null `next_cursor` means the last page.
+- 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.
@@ -147,6 +168,7 @@ The generated contract contains only objects declared in the manifest.
 
 - The contract removes `create` when `canCreate` is false.
 - The contract removes `delete` when `canDelete` is false.
+- The contract removes `update` and `updateWhere` when `readWrite` is empty.
 - Treat a missing method as a missing manifest grant, and edit the manifest when required.
 - Run generation after a manifest or Hitch schema change.
 - Do not bypass the contract with a cast.

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

@@ -2,6 +2,12 @@
 
 Use a schedule to call an applet server procedure from a cron expression.
 
+## Local dev
+
+The dev server does not run cron.
+Run `pnpm --dir applets/<code> exec applet schedules run <schedule>` from the workspace root while `pnpm --dir applets/<code> run dev` runs.
+The run acts as you, not as the applet. The run writes real data.
+
 ## Define the target procedure
 
 - Add the target to the applet's server router.
@@ -44,7 +50,7 @@ schedules: [
 - The five fields are minute, hour, day of month, month, and day of week.
 - The registered router type checks the path after type generation.
 - A nested procedure uses its nested router path.
-- The scheduler invokes the named router procedure with no input.
+- The scheduler invokes the named router procedure with the input `{}`. Accept an empty object or declare no input.
 
 ## Understand the run identity
 
@@ -82,5 +88,4 @@ const uploaded = await hitch.files.upload(file);
 - Read the stored status, path, HTTP status, and error details.
 - Check the applet logs for procedure details.
 - Follow the log commands in the main Hitch applet skill.
-- Include `--level log` during diagnosis.
 - Do not log secrets, tokens, or personal data.

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

@@ -29,9 +29,6 @@ export default { router };
 ```
 
 - Nest procedure objects when the applet needs nested paths.
-- Do not name a top-level procedure `hitch`.
-- The client reserves `hitch` for the Hitch data client.
-- The generated API client type rejects a router with that reserved key.
 
 ## Call the router from the client
 

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

@@ -2,6 +2,15 @@
 
 Use a workflow for server work that runs in steps, retries a step, or waits between steps.
 
+## Local dev
+
+In `pnpm --dir applets/<code> run dev`, workflows run in the dev server as you. The server keeps runs in memory.
+Runs disappear when the dev server stops.
+In local dev, a step fails when it runs longer than 5 minutes. A deployed step can run for 15 minutes.
+Set `HITCH_DEV_SKIP_SLEEP=1` in the shell that runs `pnpm --dir applets/<code> run dev` to skip sleeps and step retry delays.
+A `.env` file does not set this value for the dev server.
+With this value, a polling loop that sleeps between checks calls Hitch without pause.
+
 ## Define a workflow
 
 - Import `createWorkflow` from `@hitch42/applet/server`.
@@ -63,11 +72,10 @@ export default { router, workflows };
 - Each step has the same limits as a scheduled run: 30,000 milliseconds of CPU and 1,000 subrequests.
 - A step that still fails after its retries throws inside the workflow function. Catch it to run a compensating step. An error you do not catch fails the run.
 - A run keeps the release it started on. A new release does not stop or change a run that is in progress or asleep.
-- An owner or admin can terminate an open run from the applet settings page. A terminated run has the status `terminated` and does not resume.
+- The owner or a member with the `applets:manage` capability can terminate an open run from the applet settings page. A terminated run has the status `terminated` and does not resume.
 
 ## Diagnose a failed run
 
 - Call `get(id)` and read `error`.
 - Workflow step output is in the applet logs with the type `workflow`, the run id, and the workflow code.
-- Run `applet logs <code> --run <id>` to see one run.
-- Include `--level log` during diagnosis.
+- Run `pnpm --dir applets/<code> exec applet logs --run <id>` from the workspace root to see one run.