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

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/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,30 +117,33 @@ 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.
 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({
@@ -147,6 +170,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.

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

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

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

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

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

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

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

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