@hitch42/applet 0.1.0-beta.10

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

@@ -0,0 +1,198 @@
+# Applet manifest
+
+Define the applet manifest in `applet.manifest.ts`.
+
+The authored definition omits `org`.
+The applet tool reads `org` from `hitch.config.ts` in the workspace root.
+
+## Use top-level fields
+
+- `org` identifies the Hitch organization.
+- `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.
+- `devDependencies` optionally declares applet build packages.
+
+The manifest and applet definition reject unknown fields.
+
+## Set `org`
+
+- Use a non-empty organization code.
+- Start the code with a lowercase letter.
+- End the code with a lowercase letter or number.
+- Use only lowercase letters, numbers, and non-consecutive hyphens.
+- Do not put `org` in `applet.manifest.ts`.
+- Set it in the root `hitch.config.ts` file.
+
+## Set `name`
+
+- Use a string with 1 through 120 characters after trimming.
+- Use the name as the applet display name.
+
+## Set `code`
+
+- Start the code with a lowercase letter.
+- End the code with a lowercase letter or number.
+- Use only lowercase letters, numbers, and non-consecutive underscores.
+- Make the applet directory name equal to the code.
+- Rename the directory or change the code when they differ.
+- 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.
+
+```ts
+objects: [
+  {
+    code: "deals",
+    canCreate: true,
+    canDelete: false,
+    readOnly: ["created_by"],
+    readWrite: ["stage", "amount"],
+  },
+],
+```
+
+Each object entry has five required fields.
+
+- `code` identifies the Hitch object.
+- `canCreate` is a boolean that controls the generated `create` method.
+- `canDelete` is a boolean that controls the generated `delete` method.
+- `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.
+- Do not list `id`, `name`, or `expected_version` as an attribute code.
+- Do not repeat an attribute code in one list.
+- Do not put one attribute code in both lists.
+
+The object declaration caps record access for the applet identity.
+
+- 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.
+
+Client requests use the current user's identity and access.
+Scheduled requests use the applet identity and its manifest cap.
+
+## Declare variables
+
+Declare variable names and policies without values.
+
+```ts
+variables: {
+  API_URL: {},
+  API_TOKEN: { secret: true },
+  REPORT_CHANNEL: { optional: true },
+},
+```
+
+- Start each key with a letter or underscore.
+- Use only letters, numbers, and underscores after the first character.
+- Use at most 128 characters.
+- Do not use a key that starts with `HITCH_`, without regard to letter case.
+- Set `secret` to a boolean to mark how the platform stores the value.
+- Set `optional` to a boolean to control whether the value is required.
+- Omit `optional` or set it to false for a required variable.
+- Set variable values on the platform.
+- Do not put variable values in the manifest or source code.
+- Read declared variables from `env` in server code.
+- Expect an optional variable to have type `string | undefined`.
+- Expect a required variable to have type `string`.
+
+## Declare schedules
+
+Each schedule calls one registered server procedure.
+
+```ts
+schedules: [
+  {
+    code: "refresh_cache",
+    name: "Refresh cache",
+    cron: "*/5 * * * *",
+    path: "/refreshCache",
+  },
+],
+```
+
+- `code` gives the schedule a stable code.
+- `name` gives the schedule a display name.
+- `cron` sets its run times.
+- `path` selects a server router procedure.
+
+Apply these validation rules.
+
+- Use the applet code format for each schedule code.
+- Do not declare the same schedule code more than once.
+- Use a name with 1 through 120 characters after trimming.
+- Use a valid five-field cron expression.
+- Put fields in minute, hour, day-of-month, month, and day-of-week order.
+- Start `path` with one `/`.
+- Do not start `path` with `//`.
+- Do not put whitespace in `path`.
+- Keep `src/server/main.ts` when the manifest has a schedule.
+
+Generation registers the server router type.
+After generation, `path` accepts only paths from that registered router.
+Before router registration, the path type falls back to `string`.
+
+## Declare packages
+
+Add direct package requirements to the manifest.
+
+```ts
+dependencies: {
+  "date-fns": "^4.1.0",
+},
+devDependencies: {
+  "@types/example": "^1.0.0",
+},
+```
+
+- Put runtime imports in `dependencies`.
+- Put build and test tools in `devDependencies`.
+- Do not add a package that the applet CLI already supplies.
+- Do not put one package in both dependency groups.
+- Use package ranges that pnpm accepts.
+- Run `applet generate`, `applet build`, or `applet deploy` to update generated package files.

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

@@ -0,0 +1,37 @@
+# Markdown
+
+Use the SDK components to edit and render markdown with Hitch file images.
+
+## Edit markdown
+
+`MarkdownEditor` is a controlled Tiptap WYSIWYG editor. Store its markdown value in your form state. Pass `hitch.files` for image paste and drop.
+
+The editor supports GFM tables and task lists. A plain table serializes as GFM. A table with block content in a cell (for example a list) serializes as inline HTML, which the `Markdown` renderer also renders.
+
+```tsx
+import { hitch } from "@hitch42/applet/client";
+import { MarkdownEditor } from "@hitch42/applet/react";
+
+<MarkdownEditor value={value} onChange={setValue} files={hitch.files} />;
+```
+
+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.
+
+While an upload runs, the editor shows the image from a temporary local URL and blocks native form submission, so a form cannot save a half-done upload. A failed upload removes the image and calls `onUploadError` if you pass one; without it, the editor logs the error and continues with the next file.
+
+## Render markdown
+
+Pass the same files surface to `Markdown`:
+
+```tsx
+import { hitch } from "@hitch42/applet/client";
+import { Markdown } from "@hitch42/applet/react";
+
+<Markdown files={hitch.files}>{value}</Markdown>;
+```
+
+`Markdown` calls `hitch.files.download(id)` to replace each Hitch file id with a fresh download link.
+
+Store markdown with `hitch-file://` file ids. Never store a presigned download URL because it expires.

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

@@ -0,0 +1,176 @@
+# Records
+
+Use the generated Hitch contract as the typed data plane.
+
+- Import `hitch` from `@hitch42/applet/client` in client code.
+- Import `hitch` from `@hitch42/applet/server` in server code.
+- Read object codes, attribute codes, inputs, and outputs from the generated types.
+- Use only the target applet's `.hitch` types as schema evidence.
+- Never copy or infer types from a sibling applet.
+- If the target applet has no generated types, resolve generation before you write record code.
+- Do not add local copies of generated types.
+- Do not use a cast to restore a missing object, field, or operation.
+
+## Use record verbs
+
+- `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`, `history`, `update`, and `delete`.
+- Pass record fields in `body` for `create` and `update`.
+- Pass structured query data in `body` for `query`.
+
+## Call records from the client
+
+Use TanStack Query options from each generated procedure.
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+import { hitch } from "@hitch42/applet/client";
+
+const deals = useQuery(
+  hitch.records.deals.query.queryOptions({
+    input: {
+      body: { filter: { stage: { $eq: "open" } }, limit: 25 },
+    },
+  }),
+);
+```
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+import { hitch } from "@hitch42/applet/client";
+
+const createDeal = useMutation(hitch.records.deals.create.mutationOptions());
+
+createDeal.mutate({ body: { name: "New deal" } });
+```
+
+- Use `.queryOptions(...)` for reads and `.mutationOptions(...)` for writes.
+- The client uses the current user's identity and access.
+- Do not add a server proxy for normal access control or filtering.
+
+## Call records from the server
+
+```ts
+import { hitch } from "@hitch42/applet/server";
+
+const deals = await hitch.records.deals.query({
+  body: { filter: { stage: { $eq: "open" } }, limit: 25 },
+});
+
+const deal = await hitch.records.deals.get({
+  params: { id: dealId },
+});
+```
+
+- 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`.
+
+```ts
+const page = await hitch.records.deals.query({
+  body: {
+    filter: {
+      $and: [{ stage: { $in: ["open", "won"] } }, { amount: { $gte: 1000 } }],
+    },
+    sort: { attribute: "amount", direction: "desc" },
+    limit: 50,
+    cursor,
+    include: "company",
+  },
+});
+```
+
+- Use `$and` or `$or` with a non-empty array of filter nodes.
+- Use `$not` with one filter node.
+- Put more than one field in a node to combine those fields with AND.
+- 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 `$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.
+- 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, 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 `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 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.
+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({
+  body: { filter, aggregates, groupBy },
+});
+```
+
+## Update matching records
+
+Pass `filter`, `set`, optional `expect`, and optional `limit` to `updateWhere`.
+
+```ts
+const result = await hitch.records.deals.updateWhere({
+  body: { filter, set: { stage: "closed" }, expect: 3 },
+});
+```
+
+- Use a nonnegative integer for `expect`.
+- Use generated types for query, aggregate, group, set, and limit values.
+
+## Fix a missing method
+
+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

@@ -0,0 +1,91 @@
+# Scheduled runs
+
+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.
+- Use `os.handler` to define the procedure.
+- Default-export `{ router }`.
+
+```ts
+import { os } from "@orpc/server";
+
+const router = {
+  refresh: os.handler(async () => {
+    // Run the scheduled work.
+  }),
+};
+
+export default { router };
+```
+
+## Declare the schedule
+
+- Add a `schedules` entry to the applet manifest.
+- Give each schedule a unique `code`.
+- Give each schedule a non-empty `name`.
+- Use a valid five-field cron expression.
+- Set `path` to the server procedure path.
+- Start the path with `/`.
+- Do not add whitespace to the path.
+
+```ts
+schedules: [
+  {
+    code: "refresh",
+    name: "Refresh data",
+    cron: "*/5 * * * *",
+    path: "/refresh",
+  },
+],
+```
+
+- 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 the input `{}`. Accept an empty object or declare no input.
+
+## Understand the run identity
+
+- A scheduled run acts as the applet.
+- It has no current user.
+- Hitch data calls use the applet's manifest grants.
+- The manifest grants set the maximum data access.
+- User-only endpoints return HTTP 403.
+- Admin-only endpoints return HTTP 403.
+
+## Keep work within the run limits
+
+- Each run has a 30,000 millisecond CPU limit.
+- Each run has a 1,000 subrequest limit.
+- Keep the procedure within both limits.
+- The scheduler prevents overlap for 16 minutes after an active run starts.
+- A later due run can start after that overlap window.
+
+## Upload files from a run
+
+- Import `hitch` from `@hitch42/applet/server`.
+- Call `hitch.files.upload(file)` with a web `File`.
+- The upload uses the scheduled run's applet identity.
+- The file bytes go directly to storage through a presigned URL.
+
+```ts
+import { hitch } from "@hitch42/applet/server";
+
+const uploaded = await hitch.files.upload(file);
+```
+
+## Diagnose a failed run
+
+- Check the applet invocation history first.
+- 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.
+- Do not log secrets, tokens, or personal data.

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

@@ -0,0 +1,95 @@
+# Applet server
+
+Use the server half for work that must not run in the browser.
+
+## Choose the correct half
+
+- Stay client-only for normal Hitch data queries and mutations.
+- The client SDK uses the current user's identity and access.
+- Use the server half for secrets.
+- Use the server half for external services.
+- Use the server half for imperative Hitch data access.
+- Do not add a server proxy only for filtering or access control.
+
+## Define the router
+
+- Import `os` from `@orpc/server`.
+- Build an object that contains oRPC procedures.
+- Define each procedure with `os.handler`.
+- Default-export `{ router }`.
+
+```ts
+import { os } from "@orpc/server";
+
+const router = {
+  hello: os.handler(() => ({ hello: "World!" })),
+};
+
+export default { router };
+```
+
+- Nest procedure objects when the applet needs nested paths.
+
+## Call the router from the client
+
+- Import `api` from `@hitch42/applet/client`.
+- Use its generated procedure types.
+- Use TanStack query options for a query.
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+import { api } from "@hitch42/applet/client";
+
+const greeting = useQuery(api.hello.queryOptions());
+```
+
+- Use the generated mutation options for a mutation.
+- Keep procedure inputs and outputs inferred from the router.
+
+## Access Hitch from the server
+
+Import the server exports:
+
+```ts
+import { env, hitch } from "@hitch42/applet/server";
+```
+
+- Use `hitch` for imperative calls inside a procedure.
+- A browser request makes `hitch` use that user's identity.
+- A scheduled request makes `hitch` use the applet identity.
+- A request without a complete user or applet identity receives HTTP 401.
+
+## Define variables
+
+- Add each server variable to the applet manifest.
+- Set `secret: true` for a secret value.
+- Set `optional: true` when the value can be absent.
+- Use a valid environment key.
+- Do not use a key with the reserved `HITCH_` prefix.
+
+```ts
+variables: {
+  API_URL: {},
+  API_TOKEN: { secret: true },
+  OPTIONAL_VALUE: { optional: true },
+},
+```
+
+- Read a required value as a `string` from `env`.
+- Read an optional value as `string | undefined`.
+- Use only variables declared in the manifest.
+
+```ts
+const response = await fetch(env.API_URL, {
+  headers: { authorization: `Bearer ${env.API_TOKEN}` },
+});
+```
+
+## Understand identity
+
+- A user request carries a user ID and session token.
+- Server `hitch` calls then use the user's access.
+- A scheduled run carries an applet ID and applet token.
+- Server `hitch` calls then use the applet's manifest grants.
+- A scheduled run has no user identity.
+- User-only endpoints reject the applet identity with HTTP 403.