boxel

Files (35)

• SKILL.md
• base-field-catalog.md · references/
• card-references.md · references/
• command-development.md · references/
• command-invocation-modes.md · references/
• common-imports.md · references/
• container-query-fitted-layout.md · references/
• core-concept.md · references/
• core-patterns.md · references/
• data-management.md · references/
• date-math.md · references/
• default-index-card.md · references/
• defensive-link-traversal.md · references/
• defensive-programming.md · references/
• delegated-rendering.md · references/
• design-playbook.md · references/
• enumerations.md · references/
• external-libraries.md · references/
• file-editing.md · references/
• fitted-formats.md · references/
• formatters.md · references/
• icons.md · references/
• imagedef.md · references/
• lint-workflow.md · references/
• prefers-wide-format.md · references/
• query-systems.md · references/
• quick-reference.md · references/
• qunit-testing.md · references/
• relationship-loading-state.md · references/
• searchable-fields.md · references/
• spec-usage.md · references/
• styling-design.md · references/
• template-syntax.md · references/
• theme-design-system.md · references/
• instance-correctness-scan.py · scripts/

SKILL.md (first lines)

# Boxel Development

You are generating idiomatic Boxel: **Card Definitions** in `.gts` (Glimmer TypeScript) and **Card Instances** in `.json` (JSON:API). Follow the syntax, imports, file layout, and patterns below exactly. Output must compile and run inside a Boxel realm.

---

## 🚨 Cardinal Rules (must be true before emitting any code)

| # | Fatal error if violated |
|---|--------------------------|
| 1 | `contains(CardDef)` or `containsMany(CardDef)` — use `linksTo` / `linksToMany` instead. CardDefs have identity, FieldDefs don't. |
| 2 | JS expressions in templates (e.g. `{{@model.price * 1.2}}`) — use helpers (`{{multiply ...}}`) or move to a getter. |
| 3 | Missing `export` on a CardDef or FieldDef. Nothing imports unexported classes. |
| 4 | Missing `fitted` format on a CardDef. All CardDefs need `isolated`, `embedded`, AND `fitted`. |
| 5 | **Query: `filter: { on: ref }` with no predicate. To match all cards of a type, use `filter: { type: ref }`.** `on` is a *scope* for predicates (`eq`/`contains`/`range`), not a filter itself. A bare `{ on: ref }` returns zero rows silently. |
| 6 | **Query sort: custom field without `on: ref`.** Only `lastModified`, `createdAt`, `cardURL` work as sort keys without `on`. Sorting on `lastName`, `dates.start`, anything custom — sort expression MUST include `on: ref` or the query is rejected. |
| 7 | **Query refs: hand-rolled URL or `Symbol.for('realmURL')`.** Use `codeRef(here, path, name)` and import `realmURL` (a Symbol) from `@cardstack/runtime-common`. `Symbol.for('realmURL')` produces a *different* Symbol that doesn't match what the host injected → `realms: []` → query never fires. |
| 8 | **Template helper/modifier import mismatch.** In `.gts`, `fn`, `on`, `concat`, `get`, `array`, `hash`, Boxel UI predicates, and formatters must be imported explicitly. Do **not** use `(perform ...)` in strict-mode templates and do **not** import `ember-concurrency/helpers/perform`. Trigger tasks through a scoped handler like `startSave = () => this.saveTask.perform();` and bind `{{on 'click' this.startSave}}`. Run the import preflight in `references/common-imports.md` before finalizing. |
| 9 | **Missing Boxel CLI lint.** Every `.gts` code change must run the installed npm `@cardstack/boxel-cli` lint gate before being called done. Use `npx boxel file lint` / `npx boxel lint`; the current monorepo CLI has no `npx boxel check`. Clean means `No lint issues found` or JSON with an empty `messages` array. See `references/lint-workflow.md`. |
| 10 | **Inline media/binary in card JSON.** Never persist `data:`, `blob:`, base64, ArrayBuffer text, MP3/image bytes, or generated media payloads in `StringField`, `TextAreaField`, `outputText`, JSON attributes, or `Base64ImageField`. Media assets must be stored as realm files (`linksTo(FileDef/ImageDef/PngDef/etc.)`). For generated bytes, use `WriteBinaryFileCommand` first. |
| 11 | **`DateField` vs `DateTimeField` — schema MUST match value format.** `contains(DateField)` requires JSON value `YYYY-MM-DD` (NO `T`). `contains(DateTimeField)` requires ISO datetime with `T` (`YYYY-MM-DDTHH:MM:SS[.sss]Z`). A mismatch passes `npx boxel file lint`, writes successfully, AND indexes — then blows up at render time as `RangeError: Invalid time value` from date-fns inside `Contains.serialize`. Pick the type by whether time-of-day is meaningful (`*At` suffix → DateTimeField; `*Date`/`*On`/`hireDate`/`dob` → DateField), then keep instance values in lockstep. See `references/base-field-catalog.md`. |
| 12 | **🚨 External URLs in JSON:API `relationships.<field>.links.self` brick the entire realm.** A relationship's `links.self` is a card identifier — relative paths (`"../Theme/foo"`) or absolute realm URLs only. **NEVER put an external image/asset URL there.** The indexer fetches the URL expecting a card document, gets binary bytes (JPEG, PNG, etc.), `JSON.parse` throws on the binary, the error message contains the binary's NULL byte, postgres rejects the JSONB write with `22P05: unsupported Unicode escape sequence`, and the transaction rolls back — taking every other card in the batch with it. The whole realm stays unindexed until the bad instance is fixed. For image URLs, use the `cardInfo` pair pattern: `@field heroImage = linksTo(ImageDef)` + `@field heroImageURL = contains(UrlField)`; the URL goes in `attributes.heroImageURL`, not the relationship. See `references/base-field-catalog.md` "Image fields — the URL/ImageDef pair pattern". |
| 13 | **🚨 `linksToMany` JSON shape uses INDEXED KEYS, never an array under `links.self`.** Each linked item in a `linksToMany` field gets its own top-level relationship key with an indexed suffix. Correct: `"activityFeed.0": { "links": { "self": "..." } }`, `"activityFeed.1": { "links": { "self": "..." } }`. WRONG (and the host rejects with "instance ... is not a card resource document"): `"activityFeed": { "links": { "self": ["...", "..."] } }`. The array-inside-`self` shape is intuitive but not valid Boxel JSON:API — `links.self` is a single string per JSON:API spec, and Boxel's encoding of "many" is indexed top-level keys. See `references/core-patterns.md` "JSON:API instance shapes". |
| 14 | **🚨 `linksTo` fields never appear in `attributes` — not even as `null`.** A `linksTo` field is serialized under `relationships`, keyed by its field path — for a linksTo nested inside a contained field, a dotted key: `"cardInfo.theme": { "links": { "self": "../Theme/foo" } }`. An empty link is `{ "links": { "self": null } }`, or omit the key entirely. Writing `"cardInfo": { "theme": null }` (or any value for the link) into `attributes` passes lint and writes successfully — then every read of the instance throws `linkTo field 'theme' cannot deserialize non-relationship value null` until the raw JSON is repaired by hand. |
| 15 | **🚨 Any function a template *calls* must be an arrow-function property, never a class method.** Glimmer invokes template-called functions (`{{if (this.isActive note) ...}}`, `{{fn this.method}}`) without binding `this`; a class body is always strict mode, so `this` is `undefined` and the first property access throws **during render**, which poisons Ember's renderer — the whole application freezes until reload. Lint passes, and `{{on}}` handlers mask the same mistake (there it merely breaks one handler). Write `isActive = (note: string) => this.activeNotes.has(note);`, never `isActive(note: string) { ... }`. Getters are safe (the template reads them off `this`); `@action` methods also bind, but arrow properties are the convention. See `boxel-workspace-cardinal-rules/SKILL.md` #11. |
| 16 | **A URL that points at a Boxel realm resource is a link, never a string.** If a field's value is the URL of a card instance or a realm file — an absolute realm URL (`https://<realm>/Person/jane`), a relative path (`../Theme/foo`), or any URL a realm serves — model it as `linksTo` / `linksToMany` (a `FileDef` subtype for files), **NEVER** as `contains(StringField)` or `contains(UrlField)`. A string-typed realm URL is invisible to the index: no invalidation when the target changes, no broken-link detection, no `<@fields.X />` rendering of the target, no query traversal — the reference silently goes stale when the target moves or is deleted. This is the exact complement of Rule 12: external URLs never go in relationships, and realm-resource URLs never go in string attributes. Two carve-outs: a `FileDef` subtype's own `id`/`url`/`sourceUrl` descriptor fields are strings that hold the realm file URL by design — populate them as strings, never convert them to relationships; and a curated public path routed via `hostRoutingRules` (a nav target like `/about`) is a routed path, not a resource identifier — `UrlField` is correct there. See `references/base-field-catalog.md` "Realm-resource URLs — always a relationship, never a string". |
| 17 | **🚨 No `:global()` in a card's CSS.** Card code compiles with `:global` turned off: the compiler only warns, the browser rejects the selector, and every other selector in the same comma-separated list is dropped with it. Lint and the correctness check both pass; the styles never apply. A class on a component that passes `...attributes` through (Pret UI and boxel-ui controls, a linked or compound `<@fields.x class='…' />`) is reachable with a plain scoped selector, and on Pret UI (layered) it wins; use `:deep()` only for DOM you can't put a class on. See `boxel-workspace-cardinal-rules/SKILL.md` #12. |

> **Rules 5–7 are the silent-zero-rows traps.** No error is thrown; the response is just empty, every time. Memorize them before writing any query. Full reference: [`references/query-systems.md`](references/query-systems.md).
>
> **Rule 11 is the silent-renders-then-crashes trap.** The mismatch survives every static check; only the runtime card render reveals it. Cross-check schema declarations against instance values before declaring a card family done.

## 🧠 Decision Trees

**Data shape**

```
Needs own identity / referenced from multiple places? → CardDef + linksTo
URL pointing at a card or realm file?                → linksTo / linksToMany — never StringField/UrlField (Rule 16)
Fixed set of values (status, priority)?              → enumField(StringField, { options: [{ value, label }, …] }) (see references/enumerations.md)
A date, or any value with a known shape?             → DateField, EmailField, UrlField, … — never a StringField (see references/base-field-catalog.md)
Image / document / file asset?                       → FileDef subtype + linksTo (see boxel-file-def)
Generated/uploaded media payload?                    → Write bytes with WriteBinaryFileCommand, then linksTo FileDef/ImageDef/PngDef. Never StringField data URI.
Compound data only AND list of ~1–3 items?           → FieldDef + containsMany
Compound data, list grows past 3 items?              → CardDef + linksToMany (perf — see below)
Compound data, exactly one item?                     → FieldDef + contains
Card aggregating many others: owns a chosen set?     → CardDef + linksToMany
Card aggregating many others: everything of a type?  → query (no relationship field)
```

**Query vs `linksToMany` — who owns the set.** A card showing *everything of a type in the realm* can query for it. A card owning a *particular* set — one the user curates, reorders, or would want more than one of — declares `linksToMany` and holds the links. Ask whether the user could reasonably want two of these over the same data: "2026 races" and "training runs" as separate dashboards means the set is owned, so `linksToMany`; one dashboard that is simply "everything I logged" can query. Querying is not the safe default. It looks tidier because nothing has to be linked, but membership becomes implicit and unbounded — nothing can be left out, there can be no second collection, and nothing in the JSON records that the cards belong together.

⚠️ **The `containsMany` edit-form perf trap.** The host's default edit template renders an inline editor for every field on every contained item. A FieldDef with 6 fields × 5 items = 30 inline editor components in the parent's edit form. Each keystroke re-renders all of them, producing ~1s/keystroke at this scale (measured against Swimmer + PersonalBest, 5/21/26).

Concrete rule: if a containsMany list will routinely hold **3 or more entries** AND each entry has **3 or more fields**, lift the FieldDef to a CardDef and use `linksToMany`. The editor becomes a card picker (lightweight rows) instead of N inline forms. Each linked card is edited on its own page with its own dedicated edit form.

Acceptable `containsMany`: tags (`containsMany(StringField)`), 1–2 phone numbers, a couple of social links. Unacceptable: race results, line items, addresses-with-7-fields, anything where a user will accumulate ≥3 entries with multiple fields each.

**Field extension**

```
Customizing a base field?     → import BaseField, extend it
Brand-new field type?         → extends FieldDef
Tweaking an existing field?   → extends BaseFieldName
```

**Request handling**

```
Simple/vague request (≤3 sentences, "build a X") → run the 500-Word Sprint below before emitting code
Specific/detailed request                        → skip the sprint, implement directly
```

## ⚡ 500-Word Sprint (for vague requests)

1. **Architecture** — 1 primary CardDef (max 3 for navigation), 3–5 supporting FieldDefs, relationship map, and the file layout: one module per CardDef, plus a module for each shared FieldDef, large format component, and helper set that is shared or runs to a few hundred lines (see `references/module-structure.md`).
2. **Distinction** — Unique angle, 2–3 clever fields, smart computations, interaction hooks.
3. **Design** — Mood, theme tokens, typography, one visual signature. (Consult `boxel-design`.)
4. **Scenario** — 3–4 personas, believable org, specific data, pain point, success metric.

Then emit code. Success order: **Runnable → Correct → Attractive → Evolvable.**

---

## 📚 References (read on demand)

Read a reference when its topic comes up — and batch: when several references apply to the task at hand (a new card build usually implicates a handful from this list), read them all in one multi-file read rather than one or two at a time. Every extra round of reads delays your first line of output.

Core syntax and patterns (load when topic comes up):

- `references/core-concept.md` — CardDef vs FieldDef, formats, inherited fields, CardInfo.
- `references/default-index-card.md` — The card at a workspace's root (`index.json`): what the default `Workspace` adoption gives you (Home / Library / Activity / Cmd+K), the fields worth setting, `entryPoints` as the supported way to pin a card to the root, and what changes for workspaces still on `CardsGrid`.
- `references/quick-reference.md` — Core imports, UI components, helpers, icons, file types.
- `references/common-imports.md` — Common `.gts` imports and the import preflight for `fn`, task handlers, `on`, `concat`, `get`, helpers, formatters, tasks, and host commands. Load before generating or reviewing non-trivial templates.
- `references/lint-workflow.md` — Mandatory installed npm `boxel` lint commands, local vs remote lint, clean-output interpretation, and fallback rules.
- `references/core-patterns.md` — Card definitions, computed cardTitle, field definitions, computed properties.
- `references/prefers-wide-format.md` — When `static prefersWideFormat = true` is required (app-card homes, sectioned-record nav, 3D layouts, routed pages, dashboards, slide decks). Default is `false`; the most-forgotten static property. **Decide at CardDef creation time, not after the layout looks cramped.**
- `references/template-syntax.md` — Field access, compound fields, `@fields` delegation, array handling, fallback values, and Glimmer syntax gotchas (the `{{#if (this.x)}}` parens trap, HTML-tag-shadowing block params).
- `references/file-editing.md` — Pointer to the `source-code-editing` skill, which defines the `run-realm-code` tool.
- `references/data-management.md` — File organization, JSON instance format, field value patterns, relationships.
- `references/module-structure.md` — Splitting card code across modules: one CardDef per module, format components in `components/`, helpers in plain `.ts`, the suggested 2,000-line budget per module, a worked multi-card layout with its imports, and how to move a class to a new module without breaking its instances (`adoptsFrom`, query refs, re-exports).
- `references/card-references.md` — `links.self` shapes: relative (`./Foo/bar` / `../Foo/bar`) vs absolute vs registered-prefix; FileDef-typed relationships need the file extension; `$REALM` and `@cardstack/...` rules; common silent-failure modes.
- `references/defensive-programming.md` — Optional chaining, default values, try/catch, array validation.
- `references/defensive-link-traversal.md` — Reading `linksTo`/`linksToMany` is not like `contains`: a linked slot reads `undefined` while loading and forever if broken. The per-slot contract, `linksToMany` `undefined` holes (`arr.length` unchanged), `.filter(Boolean)` before count/render, and `getRelationshipMembershipState`/`RelationshipState` for distinguishing loading vs broken.
- `references/relationship-loading-state.md` — `getRelationshipMembershipState(this, 'field').isLoading`: a live, tracked per-field boolean for driving a spinner (flagship: query-backed `linksToMany`). Observe-only — always render the field alongside its status; gating the read on the status means nothing ever resolves it.

Subsystems (load when used):

- `references/query-systems.md` — Query syntax, the `on` rule, filter types, and the display surfaces: `@context.searchResultsComponent` (entry-rooted) and `getCards`; the one "Limits and ceilings" table (getCards 100 rows / 2 realms, query fields 500/2000).
- `references/searchable-fields.md` — The `searchable` field option (`true | string | string[]`) controlling which `linksTo`/`linksToMany` targets are pulled into the search doc (contained always in; links opt-in); dotted-path routing; why a filter past a non-searchable link returns zero rows with `meta.incomplete` instead of an error.
- `references/fitted-formats.md` — Four sub-formats (badge/strip/tile/card), size classification. Quick reference only.
- **`references/design-playbook.md`** — **The recommended way to design any user-facing card.** Four-stage process: (1) mockup with no variables, (2) extract theme DNA, (3) tokenize, (4) derive fitted/embedded. Includes the verbatim design-challenge framing (Pentagram art director + internal taste-maker) and the "fitted features the media" rule. Trust your intrinsic design taste; this is a process, not a CSS rulebook.
- `references/container-query-fitted-layout.md` — Mandatory implementation standard for every `fitted` template. Prefer `FittedCard` from `@cardstack/boxel-ui/components` for standard compositions (implements the standard internally; tune via `--fc-*` variables). When hand-rolling: single-root `.fit` grid querying the host-provided `fitted-card` container (never create your own container on the root), container-query sub-formats, `pow()` typography variables, `minmax(0, 1fr)` body rows, and `min-height: 0` overflow discipline. Derive the visual layout from the design playbook first, then implement fitted with this guide.
- `references/delegated-rendering.md` — Card-to-card rendering, clickable cards, Pret UI Select/Combobox dropdowns, custom edit controls.
- `references/command-development.md` — Command structure, host commands, OpenRouter, generated binary file persistence, progress.
- `references/command-invocation-modes.md` — Taxonomy of how to expose a Command: direct call, reactive resource, card menu item, typed run card, AI processor, CLI script, atomic install. The same Command class served multiple ways.
- `references/theme-design-system.md` — Theme linking, CSS variables, canonical tokens.
- `references/styling-design.md` — CSS safety, formatters, design tokens, typography, format dimensions.
- `references/formatters.md` — Canonical `@cardstack/boxel-ui/helpers` formatter list (`formatDateTime`, `formatNumber`, `formatCurrency`, duration, file size, lists, names, ordinals, periods, age) and display-boundary guidance.

From cardstack/boxel-skills, MIT.

More from cardstack/boxel-skills