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

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,51 @@
+---
+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, attachment.
+- A value is a non-empty value or `null`. No type accepts an empty string.
+- 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,121 @@
+# 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 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.
+
+## 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                                                           | 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                 |
+
+## 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.

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

@@ -0,0 +1,150 @@
+---
+name: hitch-theory
+description: The mental model of Hitch. Read before you design, review, or explain anything that touches Hitch data, applets, access, or query cost. Use when a decision depends on what Hitch is for, what Hitch handles versus what an applet handles, how attributes and references model data, how changesets and releases move together, or who a call acts as. Pairs with hitch-applets, which holds the build procedure.
+---
+
+# Theory of Hitch
+
+This skill explains how Hitch works and why. For the build procedure, read the `hitch-applets` skill.
+
+## 1. What Hitch is
+
+Hitch is a platform for internal applications. It is not a CRM, a rostering product, a reporting product, or any other vertical. An organization builds its own rostering, job, or invoice applets on Hitch.
+
+Hitch is two layers:
+
+1. A durable data system that the organization owns: objects, attributes, records, files, identity, and grants.
+2. A governed runtime for replaceable software: applets that Hitch builds, releases, hosts, and runs.
+
+## 2. What an applet is
+
+An applet is not an app. An app is the whole machine from the old days of software: its own authentication, its own database, its own permissions, a frontend, a server, caches, a deployment pipeline, and monitoring. Every app rebuilds that machine from scratch. Every app then spends most of its life on the machine, not on the work. The organization never wanted the machine. It wanted the business logic.
+
+AI has changed the economics of software. Code is now cheap to write and cheap to change, so software can be personal to one organization, one team, and one workflow. Hitch is built for that world. Hitch flips the model. Instead of one monolithic app designed to serve many unrelated users, an organization gets a set of many applets, completely custom and personalised to its needs. An applet is the closest thing to pure business logic: one workflow, the screens it needs, and the rules that make it correct. Hitch handles everything underneath: the data and its schema, identity, permissions, files, immutable releases, hosting, schedules, and durable workflows. The author never touches the machine. The author builds only what matters to the user.
+
+Hitch takes the machine away for correctness and trust as much as for speed. Authentication, access control, schema validation, and release safety are the parts an agent gets wrong, and the parts an organization cannot afford to have wrong. Hitch handles them, so your organisation has the confidence it needs to fully adopt vibe coded software and move off of legacy SaaS systems.
+
+In practice an applet is a client-only, server-only, or full-stack application that Hitch builds, releases, hosts, and runs inside the platform trust boundary. It is not a third-party plugin.
+
+Every organization has its own tenant on Hitch. Its data, its users, its grants, and its applets all live there. When Hitch runs an applet, it runs it inside that tenant, the way AWS runs a workload inside a customer's account: the provider operates the infrastructure, but the account, the identities, and the data are the customer's. An applet sees its organization's tenant and nothing else.
+
+Applets can be used standalone via their `.app` URL or within the Hitch shell. Standalone and embedded operation use the same identity, release, routes, and theme.
+
+## 3. What Hitch handles and what an applet handles
+
+| Hitch handles                                                   | The applet handles                            |
+| --------------------------------------------------------------- | --------------------------------------------- |
+| Canonical organization records and files                        | One focused workflow and its presentation     |
+| Object and attribute schema, and references                     | Domain-specific UI composition                |
+| Validation, normalization, constraints, versions, audit         | External API adapters and translation         |
+| Organization identity, authentication, grants                   | User interactions and app-specific validation |
+| Immutable releases, schedules, the workflow engine, the runtime | Derived views and deliberate derived records  |
+| Theme delivery and platform navigation                          | Ephemeral client state                        |
+
+## 4. Why code and data are separate
+
+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 boundary gives you:
+
+- One source of truth that many applets share.
+- One set of schema and integrity rules for every writer: applets, API keys, imports, and future code.
+- Central permissions that applet UI code cannot weaken.
+- Independent applet release and rollback with no data fork.
+- Direct user-scoped reads from the browser, with no applet server proxy.
+- One place for integrations: sync an external system into Hitch once, then let other applets use the same data.
+
+Consequences:
+
+- Do not add an applet-owned database, a parallel cache, or a copied object set. If an applet seems to need its own storage, Hitch has a gap. Raise the gap instead.
+- Code rollback is not data recovery. A release switch never moves or restores records.
+- When you install, upgrade, or remove an applet, the canonical data stays where it is.
+- A domain rule can live in applet code when it controls one workflow. If the rule must hold for every writer, express it in the schema, so Hitch enforces it for every applet, API key, and import.
+- Data normalization and UI hierarchy are separate decisions. Model distinct concepts as objects plus references when their lifecycle or permissions differ. Group them on one screen when that matches the user. Do not invent child objects to solve navigation.
+
+## 5. Attributes are schema
+
+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.
+- 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.
+- Advanced filters and sorting are opt-in per attribute with the `indexed` flag. New attributes default to off. Every attribute still supports equality and not-empty filters. Aggregating or grouping by an attribute needs no flag. Type rules still apply: a reference, user, attachment, rich text, or multi-value attribute never sorts. Do not turn the flag on for every attribute. Turn it on for the attributes a query needs.
+
+References model relationships:
+
+- A reference attribute names a target object. Cardinality on each side comes from the single or multi setting of each face.
+- A reference can expose an inverse face on the target object. One face owns and stores the edges. The other face is derived. Write the owner face only.
+- Hitch keeps the links typed, clears inbound links when a target is deleted, applies grants through the inverse, and lets you filter through either face. Do not invent a join object for a plain relationship. Use a join object only when the relationship needs its own fields or lifecycle.
+
+Special cases:
+
+- A user attribute points at a membership in the same organization. Removal of the member sweeps those values.
+- 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
+
+All schema mutations go through a changeset: an ordered list of object and attribute operations with a stored evaluation.
+
+- A hard blocker means invalid schema or data. Examples: a unique constraint that finds duplicates, a required attribute with empty records, a tightened range with violators.
+- A soft blocker means a dependency. Examples: applets, grant conditions, or delegations that depend on the object or attribute.
+- Any blocker stops the apply. A submit with a blocker stages a pending changeset. The apply succeeds after the blocker is resolved.
+
+An applet release can bind to a pending changeset. Hitch checks the manifest against the schema the changeset will produce. A mismatch is a deploy warning, not a denial. The unresolved warning becomes a hard blocker on the changeset. A bound release does not go live on deploy. When the changeset applies, the schema and the newest bound release of each applet become active together. Schema and code change together.
+
+Adoption folds one pending changeset into another and abandons the source. The source must have no bound releases.
+
+The applet manifest lists the objects the applet uses, with create and delete flags, read-only attributes, and read-write attributes. That list is the access declaration. It caps what the applet identity can do: the object actions, and the attributes it can update. It does not change what a user can see.
+
+## 7. Identity and access
+
+Hitch enforces access control on every Hitch API call. An applet never re-implements it. A UI filter or a hidden control is convenience, never a boundary. An applet's own server procedure is applet code, so it must check the business rules it introduces. Every call carries a principal and Hitch applies that principal's grants.
+
+Principals:
+
+- A person, through a session or a personal API key. A personal API key inherits the member's capabilities.
+- An impersonated person. The target's capabilities must be a proper subset of the caller's.
+- An applet. The applet identity has no role and no bypass. Its authority is exactly the grants projected from its manifest.
+
+The organization roles are member and owner. There is no admin role. The owner holds every capability, bypasses every grant, and cannot be removed or impersonated. Capabilities are ten named org-wide powers: manage members, teams, objects, permissions, applets, and the organization; read all records; write all records; use applets; impersonate members. A capability grant goes to a team only, never to a person or to everyone. When one person needs a capability, put them in a one-person team. A caller can grant only a capability the caller holds.
+
+Object grants are the matrix: one row per object and grantee with create, read, update, and delete flags. A grantee is a team, an applet, or the default row that every member holds. A member's access is the union of the default row and their team rows. The read-all and write-all capabilities bypass object grants. Object grants set the verbs. Conditions narrow rows. Attribute grants restrict updates to protected attributes and applet writes. Reads are never masked per attribute.
+
+An object grant can delegate through one single-valued owner reference. The linked record then uses the same grantee's grant on the target object.
+
+Grant conditions scope rows to the current user. A condition path is a user attribute on the object, or one reference followed by a user attribute on the target object. A record whose user attribute is empty is invisible to that grant. An invisible record behaves as missing. A condition applies to read, update, and delete, never to create. A condition cannot compare a value, such as "where status equals X".
+
+Who a call acts as:
+
+- A client applet call acts as the current user. The manifest grants do not apply.
+- A schedule run acts as the applet, capped by the manifest.
+- A workflow run acts as whoever started it: the invoking user, or the applet when a schedule started it.
+
+Because Hitch enforces access, a client applet needs no server proxy for filtering or access control. Add a server only for secrets, external systems, schedules, workflows, or bounded fan-in.
+
+## 8. What makes a good applet
+
+A good applet:
+
+- Solves one related workflow for one clear group of users.
+- Uses the organization's existing Hitch data, not a private copy.
+- Presents the smallest useful set of decisions and actions. It does not reproduce a legacy product screen for screen.
+- Uses Hitch primitives before custom infrastructure.
+- Feels native through semantic theme tokens, shared interaction patterns, useful empty, loading, and error states, and viewport-safe layouts.
+- Has explicit access, performance, failure, and recovery behavior.
+- Can be replaced or rolled back with no move or rewrite of the canonical data.
+
+Split an applet when workflows, audiences, privileges, release cadence, or failure modes differ. Do not split because the UI has another page. A sync applet and a reporting applet are a good split. Ingestion has secrets, schedules, broad write grants, retries, and external failure modes. Reports read already-synced data with narrow grants.
+
+## 9. Product-design principles
+
+- Build to user outcomes, not to the screens or tables of an older system.
+- Start with the important nouns, relationships, permissions, and failure cases. Design screens after that.
+- Simplify critically. Defer speculative channels and infrastructure.
+- Ship the smallest complete workflow. Add nothing unrequested.
+- Treat thresholds, status rules, timing, channels, and recipients as product decisions for the user.
+- Confirm destructive or external writes. Show the target, the intended change, the stale-source check, and the outcome. A Hitch mutation and a mutation of an external source are not equivalent.
+- Record rejected designs and the reason. Do not rebuild what was deliberately cut.

package/scaffold/.github/workflows/hitch.yml

@@ -2,12 +2,6 @@ name: Deploy Hitch applets
 
 on:
   push:
-    paths:
-      - "applets/**"
-      - ".github/workflows/hitch.yml"
-      - "hitch.config.ts"
-      - "pnpm-lock.yaml"
-      - "pnpm-workspace.yaml"
 
 permissions: {}
 
@@ -18,4 +12,4 @@ jobs:
       contents: read
       id-token: write
     # Hitch verifies the called workflow's commit SHA from the OIDC token.
-    uses: hitch-42/actions/.github/workflows/deploy.yml@main
+    uses: hitch-42/actions/.github/workflows/deploy.yml@1a76e4936f94730e20710b455fa0a06564929f39

package/dist/build-BqoQ-uNz.js

@@ -1,2 +0,0 @@
-import { n as runBuild } from "./build-Ch3pALLA.js";
-export { runBuild };

package/dist/generate-CRVA0Ll5.js

@@ -1,2 +0,0 @@
-import { n as runGenerate } from "./generate-BuszZ9-U.js";
-export { runGenerate };

package/dist/load-config-BnxocLAQ.js

@@ -1,56 +0,0 @@
-import { a as ORG_CODE_PATTERN, r as appletSourceDefinitionSchema } from "./manifest-DyoJ1MIL.js";
-import { createRequire } from "node:module";
-import { z } from "zod";
-import { existsSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
-import { loadConfigFromFile } from "vite";
-//#region src/workspace.ts
-const hitchConfigSchema = z.object({
-	sdk: z.string().min(1),
-	org: z.string().regex(ORG_CODE_PATTERN)
-});
-const require = createRequire(import.meta.url);
-function readWorkspaceConfig(dir) {
-	const path = resolve(dir, "hitch.config.ts");
-	if (!existsSync(path)) return void 0;
-	let module;
-	try {
-		module = require(path);
-	} catch (error) {
-		throw new Error(`Failed to load ${path}.`, { cause: error });
-	}
-	const config = hitchConfigSchema.safeParse(module !== null && typeof module === "object" && "default" in module ? module.default : module);
-	if (!config.success) throw new Error(`Invalid Hitch config in ${path}: ${config.error.message}`);
-	return config.data;
-}
-function resolveWorkspaceOrg(appletRoot) {
-	const appletsDir = dirname(appletRoot);
-	if (basename(appletsDir) === "applets") {
-		const config = readWorkspaceConfig(dirname(appletsDir));
-		if (config !== void 0) return config.org;
-	}
-	throw new Error(`No Hitch workspace found for ${appletRoot}. An applet must live at <workspace>/applets/<code> with hitch.config.ts in the workspace root.`);
-}
-//#endregion
-//#region src/typegen/load-config.ts
-async function loadAppletSourceDefinition(root) {
-	const path = resolve(root, "applet.manifest.ts");
-	if (!existsSync(path)) throw new Error(`No applet manifest found at ${path}.`);
-	const loaded = await loadConfigFromFile({
-		command: "build",
-		mode: "production"
-	}, path, root);
-	if (loaded === null) throw new Error(`No applet manifest found at ${path}.`);
-	const parsed = appletSourceDefinitionSchema.safeParse(loaded.config);
-	if (!parsed.success) throw new Error(`Invalid applet manifest at ${loaded.path}: ${parsed.error.message}`);
-	return parsed.data;
-}
-async function loadAppletConfig(root) {
-	const { dependencies: _dependencies, devDependencies: _devDependencies, ...definition } = await loadAppletSourceDefinition(root);
-	return {
-		org: resolveWorkspaceOrg(root),
-		...definition
-	};
-}
-//#endregion
-export { resolveWorkspaceOrg as i, loadAppletSourceDefinition as n, readWorkspaceConfig as r, loadAppletConfig as t };