@hitch42/applet 0.1.1-beta.8 → 0.1.1-beta.9

package/dist/{workspace-XVtM12ZC.js → workspace-D0dnnlxL.js}

@@ -45,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");
@@ -113,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,
@@ -124,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"
@@ -169,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) {
@@ -182,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] = {
@@ -291,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);
@@ -319,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,
@@ -356,23 +356,18 @@ function findWorkspaceConfig(cwd) {
 }
 //#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));
 		rejectEnvironmentKey(response, auth);
 		if (response.status !== 401) return response;
 	}
-	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,
-		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));
 }
@@ -387,4 +382,4 @@ function resolveWorkspaceOrg(appletRoot) {
 	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 };
+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.8",
+  "version": "0.1.1-beta.9",
   "license": "MIT",
   "bin": {
     "applet": "./dist/applet.js"
@@ -42,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",
@@ -53,7 +58,6 @@
     "@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",
@@ -64,18 +68,22 @@
     "@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",
@@ -105,6 +113,6 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org",
-    "tag": "beta"
+    "tag": "latest"
   }
 }

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

@@ -28,6 +28,10 @@ This file holds the common rules. Read each matching reference before you edit a
 
 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`.
@@ -50,17 +54,18 @@ For attribute types, filters, and API limits, read `../hitch-data/SKILL.md`. To
 - 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 Stop preview or close the tab.
+- 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`, 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.
+- 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`.
+- 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`.
 
@@ -132,6 +137,25 @@ Read `references/files.md` before download links, attachment attributes, or serv
 - 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:
@@ -139,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
 ```
@@ -150,7 +176,7 @@ If a command fails, report the exact blocker. Do not deploy as a verification st
 ## 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.
+- 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/manifest.md

@@ -83,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.

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

@@ -15,6 +15,8 @@ import { MarkdownEditor } from "@hitch42/applet/react";
 <MarkdownEditor value={value} onChange={setValue} files={hitch.files} />;
 ```
 
+Pass `autoFocus` to put the cursor at the end of the text when the editor mounts. It is off by default, so the editor never takes focus from another field.
+
 The editor uploads pasted or dropped images. It stores each image as `![name](hitch-file://<file-id>)`.
 
 The `files` value must supply both `upload(file)` and `download(id)`. The editor uses `download(id)` to show stored Hitch images.

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 a record 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`.
@@ -122,6 +142,8 @@ Each aggregate can have its own `filter` with the same syntax as the top-level `
 The array form returns `keys` and `labels` arrays per group.
 The object form orders category groups by an aggregate value (top-N by value).
 The array form orders each dimension by key; `limit` selects the first N distinct keys in that order. It does not support top-N by value.
+Grouped results include `truncated`. When it is `true`, the limit omitted groups.
+Narrow the filter or split the query.
 
 ```ts
 const totals = await hitch.records.deals.aggregate({

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

@@ -24,8 +24,9 @@ An organization's data lives in Hitch objects. Each object has attributes. Each
 ## 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.
+- Types: text, rich_text, integer, decimal, currency, checkbox, date, datetime, time, domain, url, email, phone, select, reference, user, organization, attachment.
 - A value is a non-empty value or `null`. No type accepts an empty string.
+- An organisation attribute points at a connected organisation; null means internal only; at most one exists per object.
 - 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.

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

@@ -13,7 +13,7 @@ Hitch validates and normalizes every attribute value on write. Read this before
 - 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`.
+- Every attribute accepts the `$eq` and `$not_empty` filters. Every attribute except checkbox and organization accepts `$in`. Other operators and `sort` need the `indexed` flag. Read `limits.md`.
 
 ## Text and rich text
 
@@ -91,6 +91,12 @@ Hitch validates and normalizes every attribute value on write. Read this before
 - Read: the UUID. With `include`, the expansion is `{ id, firstName, lastName, email }`.
 - Filters: identity operators only. Sort: never.
 
+## Organisation
+
+- An organisation attribute points at a connected organisation; null means internal only; at most one exists per object.
+- Write an accepted peer organization UUID. The value stays visible after the connection ends.
+- With `include`, the expansion is `{ id, name }`. Filters are `$eq` and `$not_empty` only.
+
 ## 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`.

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

@@ -22,19 +22,19 @@ A page is the unit of a read. A screen shows one page and asks for the next one.
 
 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                 |
+| 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                                                           | Extra groups omitted, `truncated: true` |
+| Distinct keys per dimension, max        | 200                                                          | HTTP 400                                |
+| 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
 

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

@@ -45,7 +45,7 @@ Applets can be used standalone via their `.app` URL or within the Hitch shell. S
 
 The organization's Hitch data is the single source of truth. An applet reads and writes that data. It does not keep its own copy.
 
-The data layer stands on its own so that every way of using it is a client of the same thing. An applet, the `hitch` command line, an MCP server for an AI agent, an API key in a script, and an import all speak to the same objects, the same schema, and the same permissions. None of them is a bridge bolted on later. Each one is generated from the organization's own schema, so it knows the organization's objects by name. Each one acts as the person or applet behind it, so it sees exactly what that caller may see. The result is that a person in a browser, an agent in a chat window, and a script in a terminal all work on the same records under the same rules, and each gets the interface that suits them. Software stops being one product with one screen and becomes your organizational data with many doors.
+The data layer stands on its own so that every way of using it is a client of the same thing. An applet, the `hitch` command line, an MCP server for an AI agent, an API key in a script, and an import all speak to the same objects, the same schema, and the same permissions. None of them is a bridge bolted on later. The CLI and applet doors are generated from the organization's own schema. The MCP door has a fixed set of record tools and reads each object's live schema at runtime with `get_object_schema`. Each one acts as the person or applet behind it, so it sees exactly what that caller may see. The result is that a person in a browser, an agent in a chat window, and a script in a terminal all work on the same records under the same rules, and each gets the interface that suits them. Software stops being one product with one screen and becomes your organizational data with many doors.
 
 The boundary gives you:
 
@@ -68,7 +68,7 @@ Consequences:
 
 An attribute is schema, not a free JSON field. Hitch validates each value against its type and configuration, normalizes it, stores it in the record, and indexes it when asked. A value that should be a select or a reference, but is stored as free text, cannot be grouped or filtered well later.
 
-- Types: text, rich text, integer, decimal, currency, checkbox, date, datetime, time, domain, url, email, phone, select, reference, user, attachment.
+- Types: text, rich text, integer, decimal, currency, checkbox, date, datetime, time, domain, url, email, phone, select, reference, user, organisation, attachment.
 - Cardinality is configuration, not a type. Text, select, reference, user, and attachment can be multi-value. A multi-value is an ordered array.
 - An empty attribute reads as null. A required multi-value attribute rejects an empty array.
 - Uniqueness is a real constraint, per attribute, per organization.
@@ -83,6 +83,7 @@ References model relationships:
 Special cases:
 
 - A user attribute points at a membership in the same organization. Removal of the member sweeps those values.
+- An organisation attribute points at a connected organisation; null means internal only; at most one exists per object.
 - An attachment attribute holds file IDs. Files live outside records, in their own storage. Create the file, upload it, then store the ID on the record.
 
 ## 6. Changesets and releases move together

package/scaffold/.agents/skills/react-best-practices/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: react-best-practices
+description: Client React performance guidelines. Use when writing, reviewing, or refactoring React components, client data fetching, bundles, rendering, or browser performance.
+license: MIT
+metadata:
+  version: "1.0.0"
+---
+
+# React Best Practices
+
+Performance guidance for client React applications. The rules focus on browser behavior, client data fetching, bundles, rendering, and re-renders.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Writing new React components
+- Implementing client data fetching
+- Reviewing code for performance issues
+- Refactoring existing React code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category                  | Impact      | Prefix       |
+| -------- | ------------------------- | ----------- | ------------ |
+| 1        | Eliminating Waterfalls    | CRITICAL    | `async-`     |
+| 2        | Bundle Size Optimization  | CRITICAL    | `bundle-`    |
+| 3        | Client-Side Data Fetching | MEDIUM-HIGH | `client-`    |
+| 4        | Re-render Optimization    | MEDIUM      | `rerender-`  |
+| 5        | Rendering Performance     | MEDIUM      | `rendering-` |
+| 6        | JavaScript Performance    | LOW-MEDIUM  | `js-`        |
+| 7        | Advanced Patterns         | LOW         | `advanced-`  |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-analyzable-paths` - Prefer statically analyzable imports
+- `bundle-dynamic-imports` - Use React.lazy for heavy components
+- `bundle-defer-third-party` - Split non-critical libraries from the initial bundle
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 4. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-split-combined-hooks` - Split hooks with independent dependencies
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+- `rerender-no-inline-components` - Don't define components inside components
+
+### 5. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Track async action pending state with useTransition
+- `rendering-resource-hints` - Use React DOM resource hints for preloading
+- `rendering-script-defer-async` - Use defer or async on script tags
+
+### 6. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+- `js-flatmap-filter` - Use flatMap to map and filter in one pass
+- `js-request-idle-callback` - Defer non-critical work to browser idle time
+
+### 7. Advanced Patterns (LOW)
+
+- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references