From 055f0f18b6c81c3c7d8635d0022e6f40bfb3fdf1 Mon Sep 17 00:00:00 2001
From: Matic Jurglic <matic.jurglic@cardstack.com>
Date: Thu, 16 Jul 2026 08:58:22 +0000
Subject: [PATCH] Reimport skills from boxel-workspaces (removes edit-tracking
 convention)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Full reimport via scripts/import-from-workspaces.mjs against the current
boxel-workspaces source. Headline change is retiring the `.gts`
edit-tracking convention — the line-1 `// ═══ [EDIT TRACKING: ON] Mark
all changes with ⁿ ═══` banner, the sequential `// ⁿ` markers, and all
prose/rules/checklists/examples that taught it — including removing the
tracking Cardinal Rule and renumbering the remaining rules 1–13.

Because this is a faithful reimport (not a scoped delta), it also carries
the other content that had drifted ahead in boxel-workspaces since the
last sync (boxel-environment references, integration-surfaces, and
write-text-file/`.json` wording in source-code-editing / glossary /
file-editing / boxel-create-instance).

Verified: `import-from-workspaces.mjs --check` reports the checkout
matches the source.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Hyod3e9qr2vwrN421Pjv4E
---
 commands/boxel-add-field.md                   |  1 -
 commands/boxel-create-instance.md             |  8 +--
 commands/boxel-debug-runtime.md               |  2 +-
 commands/boxel-edit-template.md               |  2 +-
 commands/boxel-search-cards.md                |  2 +-
 index.md                                      | 14 +++---
 skills/boxel-create-edit-cards/SKILL.md       |  2 +-
 skills/boxel-environment/SKILL.md             | 10 ++--
 .../references/calling-commands.md            | 17 +++----
 .../references/card-tool-selection.md         | 11 ++--
 .../references/host-commands-reference.md     |  8 +--
 .../references/source-code-editing.md         |  3 +-
 .../references/workflows-and-orchestration.md |  4 +-
 skills/boxel-patterns/SKILL.md                |  2 +-
 .../patterns/attach-remote-image/README.md    |  4 +-
 .../example.gts                               | 31 ++++--------
 .../show-count-tiles-from-query/example.gts   |  2 +-
 .../references/integration-surfaces.md        |  6 +--
 skills/boxel/SKILL.md                         | 27 +++++-----
 skills/boxel/references/core-patterns.md      | 16 +++---
 .../boxel/references/defensive-programming.md |  4 +-
 .../boxel/references/delegated-rendering.md   |  6 +--
 skills/boxel/references/file-editing.md       |  5 +-
 skills/boxel/references/imagedef.md           |  2 +-
 skills/boxel/references/lint-workflow.md      |  2 +-
 skills/boxel/references/quick-reference.md    | 17 +++----
 skills/boxel/references/template-syntax.md    |  2 -
 .../scripts/instance-correctness-scan.py      |  2 +-
 skills/glossary.md                            |  4 +-
 skills/source-code-editing/SKILL.md           | 50 ++-----------------
 30 files changed, 100 insertions(+), 166 deletions(-)

diff --git a/commands/boxel-add-field.md b/commands/boxel-add-field.md
index 8ff33c7..c9673e9 100644
--- a/commands/boxel-add-field.md
+++ b/commands/boxel-add-field.md
@@ -39,7 +39,6 @@ boxel:
 - [ ] The new field uses `linksTo`/`linksToMany` if it points at a CardDef, `contains`/`containsMany` if FieldDef.
 - [ ] Computed fields wrap field access in try/catch when crossing card boundaries.
 - [ ] No self-referencing computed fields.
-- [ ] Tracking marker `ⁿ` added on every changed line (if tracking mode is on).
 - [ ] Changed `.gts` files passed installed npm `boxel` lint (`npx boxel file lint ... --file <local-file>` before push and `npx boxel lint <path> --realm <url>` after push).
 
 ## Failure Recovery
diff --git a/commands/boxel-create-instance.md b/commands/boxel-create-instance.md
index c4b27c4..31d13f2 100644
--- a/commands/boxel-create-instance.md
+++ b/commands/boxel-create-instance.md
@@ -20,7 +20,7 @@ boxel:
 
 ## Read
 
-1. `skills/boxel/SKILL.md` — cardinal rules 13-14 (external URLs in `links.self`, `linksToMany` indexed keys) plus `references/data-management.md` for the full JSON:API instance shapes (`containsMany` arrays, empty links, `adoptsFrom`).
+1. `skills/boxel/SKILL.md` — cardinal rules 12-13 (external URLs in `links.self`, `linksToMany` indexed keys) plus `references/data-management.md` for the full JSON:API instance shapes (`containsMany` arrays, empty links, `adoptsFrom`).
 2. `skills/boxel/references/card-references.md` — how every `links.self` resolves (`./` / `../` / absolute; bare paths throw). Also `references/core-concept.md` "Relationship path resolution" and "`adoptsFrom.module` — URL of the .gts, NOT including the export name".
 3. `skills/boxel/references/base-field-catalog.md` — DateField vs DateTimeField value contract; the image URL/ImageDef pair pattern.
 4. `skills/boxel-patterns/patterns/theme-first-workflow/README.md` — theme linking via `relationships["cardInfo.theme"]`, absolute URLs for nested folders, and why Theme cards omit the self-theme relationship.
@@ -29,7 +29,7 @@ boxel:
 
 ## Procedure
 
-1. Decide the tool: `write-text-file` (new instance, simple shape), `patch-fields` (existing instance, surgical), `patchCardInstance` (existing instance, full replace), or SEARCH/REPLACE (large or structural).
+1. Decide the tool: SEARCH/REPLACE with a `(new)` marker (new instance), `patch-fields` (existing instance, surgical), or `patchCardInstance` (existing instance, full replace).
 2. Compose the JSON: `"data"` envelope, `"type": "card"`, `meta.adoptsFrom` (module + name), `attributes`, `relationships` — shapes per the Read list above.
 3. Include `attributes.cardInfo` unless there's a specific reason not to (it's the user's edit surface); set `relationships["cardInfo.theme"]` when this instance should carry its own theme. Theme instances themselves omit that relationship.
 4. Match date string formats to the schema's field type (DateField vs DateTimeField); put external image URLs in the paired `*URL` attribute, never in a relationship.
@@ -39,10 +39,10 @@ boxel:
 
 - [ ] `"data"` envelope; `meta.adoptsFrom` has `module` (no export-name suffix) + `name`.
 - [ ] Every `links.self` starts with `./`, `../`, or `http` (see `card-references.md`).
-- [ ] `linksToMany` uses indexed keys, `containsMany` is an array in attributes, empty links use `"self": null` (cardinal rule 14 + `data-management.md`).
+- [ ] `linksToMany` uses indexed keys, `containsMany` is an array in attributes, empty links use `"self": null` (cardinal rule 13 + `data-management.md`).
 - [ ] `attributes` is an object (never a JSON string); `relationships` is its sibling, not nested inside it.
 - [ ] `attributes.cardInfo` present; theme linkage decided per `theme-first-workflow`; no self-theme on Theme instances.
-- [ ] Date values match field type; image URLs in the `*URL` attribute (cardinal rule 13 + `base-field-catalog.md`).
+- [ ] Date values match field type; image URLs in the `*URL` attribute (cardinal rule 12 + `base-field-catalog.md`).
 
 ## Verification after push
 
diff --git a/commands/boxel-debug-runtime.md b/commands/boxel-debug-runtime.md
index 8626aca..a194990 100644
--- a/commands/boxel-debug-runtime.md
+++ b/commands/boxel-debug-runtime.md
@@ -46,5 +46,5 @@ boxel:
 
 ## Failure Recovery
 
-- Can't reproduce → ask the user for exact reproduction steps. Boxel runtime errors often surface differently for different ages of edit-tracking state.
+- Can't reproduce → ask the user for exact reproduction steps.
 - Loop detected (same commands repeating) → STOP and tell the user. Don't barrel forward.
diff --git a/commands/boxel-edit-template.md b/commands/boxel-edit-template.md
index 1dfb100..0d5b0b0 100644
--- a/commands/boxel-edit-template.md
+++ b/commands/boxel-edit-template.md
@@ -31,7 +31,7 @@ boxel:
 ## Procedure
 
 1. Read the current template — confirm which format you're editing.
-2. SEARCH/REPLACE the template. Preserve `<style scoped>` blocks and tracking markers.
+2. SEARCH/REPLACE the template. Preserve `<style scoped>` blocks.
 3. **For `fitted`, follow `skills/boxel/references/container-query-fitted-layout.md` exactly.** Prefer `FittedCard` from `@cardstack/boxel-ui/components` for standard compositions (tune via `--fc-*` variables). When hand-rolling: single-root `.fit` grid querying the host's `fitted-card` container (no local container on the root), six height quanta, `pow()`-based typography, `minmax(0, 1fr)` body row, `min-height: 0` on grid children. Hand-rolling without these will overflow at edge sizes.
 4. For multi-card delegation, use `<@fields.x />` — don't iterate `@model` then try `<@fields.x />` inside the loop (see `template-syntax.md`).
 5. Use theme tokens per `boxel-ui-guidelines` — no hard-coded colors outside theme scope.
diff --git a/commands/boxel-search-cards.md b/commands/boxel-search-cards.md
index 3aa5cc7..6a499c9 100644
--- a/commands/boxel-search-cards.md
+++ b/commands/boxel-search-cards.md
@@ -28,7 +28,7 @@ boxel:
 
 1. If the query is title-based and simple → `SearchCardsByTypeAndTitleCommand_a959`.
 2. If the query needs filters (`eq`, `gt`, `range`) → `SearchCardsByQueryCommand_847d`.
-3. Build the type reference as `{ module: <full URL>, name: <ClassName> }`. To match **all cards of a type**, use `filter: { type: ref }`. Use `on: ref` **only** to scope predicates (`eq`/`contains`/`range`) or a custom-field sort — a bare `{ on: ref }` with no predicate returns zero rows silently (Cardinal Rule 6, `boxel/references/query-systems.md`).
+3. Build the type reference as `{ module: <full URL>, name: <ClassName> }`. To match **all cards of a type**, use `filter: { type: ref }`. Use `on: ref` **only** to scope predicates (`eq`/`contains`/`range`) or a custom-field sort — a bare `{ on: ref }` with no predicate returns zero rows silently (Cardinal Rule 5, `boxel/references/query-systems.md`).
 4. Display results — use `show-card_566f` if the user wants to see one; just list otherwise.
 
 ## Done Criteria (self-verify)
diff --git a/index.md b/index.md
index 89f80e9..84bb87d 100644
--- a/index.md
+++ b/index.md
@@ -97,19 +97,19 @@ Commands route to these supporting skills. They're documented in `skills/` and a
 - **`cardInfo.theme` is the per-instance override.** When set, it wins over whatever the CardDef's computed `cardTheme` would have returned. When the CardDef does NOT override `cardTheme`, `cardInfo.theme` is how a theme installs at all — but a Task that inherits its Project's theme doesn't need it on every Task instance.
 - **Override `cardTitle` when there's a primary field.** Respect `cardInfo.name` first, then fall back to the primary field, then to `Untitled <DisplayName>`. See pattern `cardinfo-override-title`.
 - **Build a Home app whenever you ship a card family.** When the realm contains 2+ related CardDefs (Project + Task + Person; Meet + Swimmer + Club + Result; Show + Listing + Venue), ship a `Home` CardDef alongside them: `prefersWideFormat = true`, brand masthead, one `@context.searchResultsComponent` section per CardDef in the family. The user lands there and sees the realm at a glance — no manual indexing required. See pattern [`app-card-home-with-search`](skills/boxel-patterns/patterns/app-card-home-with-search/README.md). Skip only for single-card utilities.
-- **Lint is mandatory for Boxel code work** (Cardinal Rule 10): `npx boxel file lint <path> --realm <url> --file <local-file>` before push, `npx boxel lint <path> --realm <url>` after. Prefer `npx boxel` over bare `boxel` (stale shims); there is no `npx boxel check`. Commands, clean-output criteria, and the no-shell assistant variant: [`lint-workflow.md`](skills/boxel/references/lint-workflow.md).
+- **Lint is mandatory for Boxel code work** (Cardinal Rule 9): `npx boxel file lint <path> --realm <url> --file <local-file>` before push, `npx boxel lint <path> --realm <url>` after. Prefer `npx boxel` over bare `boxel` (stale shims); there is no `npx boxel check`. Commands, clean-output criteria, and the no-shell assistant variant: [`lint-workflow.md`](skills/boxel/references/lint-workflow.md).
 - **Public-repo path hygiene.** This workspace is a public repo. Never commit absolute local filesystem paths, local usernames, or machine-specific checkout paths into tracked docs, scripts, generated bundle comments, or learning notes. Use placeholders (`/path/to/boxel`, `/path/to/bxl`, `[local checkout]`) or env vars (`BOXEL_MONOREPO`). Local paths are fine in transient shell commands, not in persisted files.
 - **Don't reach for `cancel-indexing`.** Slow indexing is not stuck indexing. Sample the indexed-card count for 5+ minutes; rising = leave it alone. `cancel-indexing --cancel-pending` discards the realm's queued TODO list and makes things worse. Last-resort recovery: `boxel file touch <one card>` → base `cancel-indexing` (never `--cancel-pending`) → `full-reindex-realm`. See [`skills/boxel-environment/references/indexing-operations.md`](skills/boxel-environment/references/indexing-operations.md).
 - **Fresh-realm push semantics.** `boxel realm push` of 30+ files via `/_atomic` can silently drop indexing jobs even when the push reports success. For > 50 instances, push kit-by-kit and verify each batch indexes (`npx boxel search` returns the expected count) before pushing the next. See indexing-operations.md "Post-push verification gate" and "The `/_atomic` batch trap".
-- **Never inline media/binary in card JSON** (Cardinal Rule 11). No `data:`/`blob:`/base64/media bytes in any string field or JSON attribute. Store media as a realm file via `linksTo(FileDef/ImageDef/PngDef)`; generated bytes go through `WriteBinaryFileCommand` first.
-- **🔴 `DateField` value = `YYYY-MM-DD` (no `T`); `DateTimeField` value = ISO datetime with `T`** (Cardinal Rule 12). A mismatch passes lint and indexes, then crashes at render (`RangeError: Invalid time value`). `*At` suffix → DateTimeField; `*Date`/`*On`/`dob` → DateField. Details: [`base-field-catalog.md`](skills/boxel/references/base-field-catalog.md).
-- **🚨 Never put an external URL in `relationships.<field>.links.self`** (Cardinal Rule 13) — the indexer fetches it expecting a card, the failed parse poisons the JSONB write, and the **whole realm's indexing transaction rolls back**. For external image URLs use the pair pattern `linksTo(ImageDef)` + `contains(UrlField)`; recipe in [`base-field-catalog.md`](skills/boxel/references/base-field-catalog.md) "Image fields — the URL/ImageDef pair pattern".
-- **🚨 `linksToMany` JSON uses indexed top-level keys** (`"activityFeed.0": { "links": { "self": "../foo" } }`), never an array under `links.self` (Cardinal Rule 14). The array shape is rejected with `"instance ... is not a card resource document"`.
+- **Never inline media/binary in card JSON** (Cardinal Rule 10). No `data:`/`blob:`/base64/media bytes in any string field or JSON attribute. Store media as a realm file via `linksTo(FileDef/ImageDef/PngDef)`; generated bytes go through `WriteBinaryFileCommand` first.
+- **🔴 `DateField` value = `YYYY-MM-DD` (no `T`); `DateTimeField` value = ISO datetime with `T`** (Cardinal Rule 11). A mismatch passes lint and indexes, then crashes at render (`RangeError: Invalid time value`). `*At` suffix → DateTimeField; `*Date`/`*On`/`dob` → DateField. Details: [`base-field-catalog.md`](skills/boxel/references/base-field-catalog.md).
+- **🚨 Never put an external URL in `relationships.<field>.links.self`** (Cardinal Rule 12) — the indexer fetches it expecting a card, the failed parse poisons the JSONB write, and the **whole realm's indexing transaction rolls back**. For external image URLs use the pair pattern `linksTo(ImageDef)` + `contains(UrlField)`; recipe in [`base-field-catalog.md`](skills/boxel/references/base-field-catalog.md) "Image fields — the URL/ImageDef pair pattern".
+- **🚨 `linksToMany` JSON uses indexed top-level keys** (`"activityFeed.0": { "links": { "self": "../foo" } }`), never an array under `links.self` (Cardinal Rule 13). The array shape is rejected with `"instance ... is not a card resource document"`.
 - **🚨 Building a kit is a sequential checklist with verification gates — lint is NOT the gate.** The seven gates, in order: (1) Stage-0 planning (thunk-by-default `() => Class` for kit-internal links; per-format content matrices), (2) import audit (base fields are **default** exports; never `ImageDef` from `/base/image`), (3) CDN-verify every icon, (4) push per-file — no atomic batches on fresh realms, (5) module-load probe (`get-card-type-schema` must return `status: ready`), (6) typed-search count gate (`boxel search` is the truth source, not lint), (7) render smoke test per CardDef. Exact commands and failure signatures: [`indexing-operations.md`](skills/boxel-environment/references/indexing-operations.md).
-- **Query traps that silently return zero rows** (Cardinal Rules 6–8): `filter: { type: ref }` to select all cards of a type — never a bare `{ on: ref }` (`on` only scopes predicates); custom sort fields require `on: ref`; build refs with `codeRef()` and import the `realmURL` Symbol from `@cardstack/runtime-common` (never `Symbol.for('realmURL')`). Details: [`query-systems.md`](skills/boxel/references/query-systems.md).
+- **Query traps that silently return zero rows** (Cardinal Rules 5–7): `filter: { type: ref }` to select all cards of a type — never a bare `{ on: ref }` (`on` only scopes predicates); custom sort fields require `on: ref`; build refs with `codeRef()` and import the `realmURL` Symbol from `@cardstack/runtime-common` (never `Symbol.for('realmURL')`). Details: [`query-systems.md`](skills/boxel/references/query-systems.md).
 - **Format choice = who owns the cell size, not what the cell looks like.** `@format='embedded'` lets the child decide its height — use for lists, feeds, roster rows. `@format='fitted'` makes the child fill a parent-controlled box — use for uniform tile grids (portraits, calendar cells). Picking fitted for a list with short content leaves empty boxes below each row. The fix is the format choice, upstream of any CSS. See "Picking the format" in [`delegated-render-control.md`](skills/boxel-ui-guidelines/references/delegated-render-control.md).
 - **Include `attributes.cardInfo` on instances when practical.** Even with all null values, the `cardInfo` object lets the user edit name/summary/theme later through the UI. It's required when the CardDef uses the default `cardTheme` pass-through AND you want a theme set per-instance.
-- Read before writing. Many `.gts` files have edit-tracking markers; reading first preserves them.
+- Read before writing. Fetch a file’s current contents before a SEARCH/REPLACE edit so the SEARCH block matches exactly.
 - Use SEARCH/REPLACE for `.gts` edits. `write-text-file` is forbidden for `.gts` (UI freezes; tool calls don't stream).
 - One CardDef per file. FieldDefs and helpers can co-locate.
 - Theme variables only — no hard-coded colors in templates. All colors live in the Theme card's `cssVariables`.
diff --git a/skills/boxel-create-edit-cards/SKILL.md b/skills/boxel-create-edit-cards/SKILL.md
index d3841cd..0e7c9d1 100644
--- a/skills/boxel-create-edit-cards/SKILL.md
+++ b/skills/boxel-create-edit-cards/SKILL.md
@@ -14,4 +14,4 @@ Read:
 1. `../boxel-environment/references/card-tool-selection.md` — the create/edit tool tables, quick decision tree, file naming, and path rules.
 2. `../boxel-environment/SKILL.md` — the master decision tree (Step 4 covers data tasks).
 
-For `.gts` edits, `source-code-editing` defines the SEARCH/REPLACE format. Never use `write-text-file` for `.gts`.
+`source-code-editing` defines the SEARCH/REPLACE format used to create and edit files (`.gts` and `.json` alike). Never use `write-text-file`.
diff --git a/skills/boxel-environment/SKILL.md b/skills/boxel-environment/SKILL.md
index 9c62b4b..2621474 100644
--- a/skills/boxel-environment/SKILL.md
+++ b/skills/boxel-environment/SKILL.md
@@ -51,7 +51,7 @@ You are the orchestrator of the Boxel AI Assistant. You decide which host comman
 ### Step 4 — Data task
 
 ```
-├─ New .json instance?                 → write-text-file (never for .gts)
+├─ New .json instance?                 → SEARCH/REPLACE with (new) marker
 ├─ Clone + modify?                     → copy-card → patch-fields
 ├─ Long markdown field (>500 chars)?  → ApplyMarkdownEditCommand_c112
 ├─ Small/targeted change?              → patch-fields_3e67
@@ -62,7 +62,7 @@ You are the orchestrator of the Boxel AI Assistant. You decide which host comman
 
 Full create/edit tool tables, file naming, and path rules: `references/card-tool-selection.md`.
 
-> **⚠️ Streaming rule:** NEVER use `write-text-file` for `.gts` files. Tool calls don't stream — the whole payload must be generated before the user sees anything, so the UI looks frozen. SEARCH/REPLACE streams visibly. (`write-text-file` is OK for `.json` instances.)
+> **⚠️ Streaming rule:** Create and edit files with SEARCH/REPLACE — avoid `write-text-file`. Tool calls don't stream — the whole payload must be generated before the user sees anything, so the UI looks frozen. SEARCH/REPLACE streams visibly for `.gts` and `.json` alike.
 
 ### Step 5 — Search / find
 
@@ -78,13 +78,13 @@ Full create/edit tool tables, file naming, and path rules: `references/card-tool
 ├─ INTERACT MODE:
 │   ├─ Display card                  → show-card_566f
 │   ├─ Create card / definition      → switch-submode_dd88 (submode: "code", createFile: true, codePath: realmUrl + filename), then SEARCH/REPLACE
-│   ├─ Switch to code                → switch-submode_dd88 (submode: "code")
-│   └─ Open workspace                → open-workspace_1696
+│   ├─ Switch to code                → switch-submode_dd88 (submode: "code"; pass codePath to target a specific realm — a bare switch stays in the current realm)
+│   └─ Open workspace                → open-workspace_1696 (lands in interact mode)
 ├─ CODE MODE:
 │   ├─ Preview card + module         → preview-format_cb94
 │   ├─ Open file in editor           → update-code-path-with-selection_f749
 │   ├─ Switch to interact            → switch-submode_dd88 (submode: "interact")
-│   └─ Open workspace                → open-workspace_1696
+│   └─ Open workspace                → open-workspace_1696 (⚠️ exits code mode — to change realm and stay in code mode, switch-submode with a codePath in that realm)
 └─ EITHER MODE:
     └─ Toggle mode                   → switch-submode_dd88
 ```
diff --git a/skills/boxel-environment/references/calling-commands.md b/skills/boxel-environment/references/calling-commands.md
index 36ba711..53e17fe 100644
--- a/skills/boxel-environment/references/calling-commands.md
+++ b/skills/boxel-environment/references/calling-commands.md
@@ -51,7 +51,7 @@
 
 **⚠️ CRITICAL CLARIFICATION:** 
 - Level 3 is NOT called "parameters" — it's just the key-value pairs INSIDE `attributes`
-- The keys at level 3 vary per command (e.g., `cardId` for show-card, `realm` + `path` for write-text-file)
+- The keys at level 3 vary per command (e.g., `cardId` for show-card, `submode` + `codePath` for switch-submode)
 - `attributes` is ALWAYS a JSON object `{ }`, NEVER a string
 
 ### 🔴 THE ONE TRUE FORMAT (Copy This Exactly)
@@ -106,22 +106,21 @@ Before generating ANY command call, verify:
 }
 ```
 
-### Example 2: write-text-file  
+### Example 2: switch-submode (multiple attributes)
 ```json
 {
-  "name": "write-text-file_e5a1",
+  "name": "switch-submode_dd88",
   "payload": {
-    "description": "Create product instance file",
+    "description": "Open code mode on a new file in the target realm",
     "attributes": {
-      "realm": "https://realm-url/",
-      "path": "Product/item.json",
-      "content": "{\"data\": {...}}",
-      "overwrite": true
+      "submode": "code",
+      "createFile": true,
+      "codePath": "https://realm-url/product-catalog.gts"
     }
   }
 }
 ```
-**Note:** `content` is a STRING containing serialized JSON or other escaped text content
+**Note:** `codePath` pins code mode to the target realm — a bare `submode` switch stays in whatever realm the UI last showed
 
 ### Example 3: Empty attributes (when no params needed)
 ```json
diff --git a/skills/boxel-environment/references/card-tool-selection.md b/skills/boxel-environment/references/card-tool-selection.md
index 48d8a9a..d94ba73 100644
--- a/skills/boxel-environment/references/card-tool-selection.md
+++ b/skills/boxel-environment/references/card-tool-selection.md
@@ -6,9 +6,9 @@ Choosing the right host-command combination for creating new cards or editing ex
 
 | Tool | Use When |
 |------|----------|
-| **SEARCH/REPLACE** | **Always use for .gts files** — new definitions, templates, any code file |
-| **write-text-file** | New .json card instances from scratch (structured data, typically small) |
+| **SEARCH/REPLACE** | **Always — any new file**, `.gts` definitions and `.json` instances alike (mark the URL line with `(new)`) |
 | **copy-card + patch-fields** | Clone existing card as template, then modify |
+| **write-text-file** | Avoid — use SEARCH/REPLACE instead (tool calls don't stream and skip the code-patch pipeline) |
 
 ## Editing Cards
 
@@ -23,10 +23,9 @@ Choosing the right host-command combination for creating new cards or editing ex
 
 ```
 Card doesn't exist yet?
-├─ New .gts file → SEARCH/REPLACE with (new) marker (ALWAYS — never write-text-file for .gts)
-├─ New .json instance → write-text-file
-├─ Clone + modify → copy-card → patch-fields
-└─ Code mode .json → SEARCH/REPLACE
+├─ New .gts file → SEARCH/REPLACE with (new) marker
+├─ New .json instance → SEARCH/REPLACE with (new) marker
+└─ Clone + modify → copy-card → patch-fields
 
 Card already exists?
 ├─ Update fields → patch-fields (preferred)
diff --git a/skills/boxel-environment/references/host-commands-reference.md b/skills/boxel-environment/references/host-commands-reference.md
index ff3bfda..1ac0779 100644
--- a/skills/boxel-environment/references/host-commands-reference.md
+++ b/skills/boxel-environment/references/host-commands-reference.md
@@ -68,8 +68,8 @@ Quick lookup of every command available to this skill, what it does, and notable
 
 ## Editing
 
-- **SEARCH/REPLACE** — Primary way to create or edit `.gts` and `.json` files. Streams as visible text so the user sees real-time progress.
-- `write-text-file_e5a1` — OK for `.json` instances. **NEVER use for `.gts` files** — tool calls don't stream, causing the UI to appear frozen during long generation. Always SEARCH/REPLACE for `.gts`.
+- **SEARCH/REPLACE** — The way to create or edit files, `.gts` and `.json` alike. Streams as visible text so the user sees real-time progress, and runs through the code-patch pipeline with correctness checking. Create a new file by marking its URL line with `(new)`.
+- `write-text-file_e5a1` — **Avoid; use SEARCH/REPLACE instead.** Tool calls don't stream, so the UI appears frozen during long generation, and the write skips the code-patch pipeline.
 - `patch-fields_3e67` — Fine-grained card field updates (requires approval).
 - `patchCardInstance` — Update card data only.
 - `ApplyMarkdownEditCommand_c112` — Edit long markdown fields (>500 chars) surgically without truncation (requires approval).
@@ -84,11 +84,11 @@ Quick lookup of every command available to this skill, what it does, and notable
 
 ## Navigation
 
-- `switch-submode_dd88` — Toggle interact/code modes. Pass `submode: "code"`, `createFile: true`, `codePath: realmUrl + filename` to create a new file from interact mode.
+- `switch-submode_dd88` — Toggle interact/code modes. A bare `submode: "code"` opens code mode in whatever realm the UI last showed — when the task targets a specific realm, always pass `codePath` with a file URL in that realm (add `createFile: true` when the file doesn't exist yet).
 - `show-card_566f` — Display card in current mode.
 - `preview-format_cb94` — Open module + preview card (code mode; use after edits).
 - `update-code-path-with-selection_f749` — Open file in code editor.
-- `open-workspace_1696` — Navigate to workspace by URL.
+- `open-workspace_1696` — Navigate to a workspace by URL. Lands in **interact mode** — it exits code mode. To work on a specific realm in code mode, use `switch-submode` with a `codePath` in that realm instead.
 
 ## Search
 
diff --git a/skills/boxel-environment/references/source-code-editing.md b/skills/boxel-environment/references/source-code-editing.md
index ef0ba75..9f6cc4d 100644
--- a/skills/boxel-environment/references/source-code-editing.md
+++ b/skills/boxel-environment/references/source-code-editing.md
@@ -8,8 +8,7 @@ When you need to edit a `.gts` or `.json` file from inside the Boxel app, load t
 - Trigger: any code-change intent — adding/editing imports, fields, templates, computed properties, or creating new `.gts` files.
 
 Key reminders for the runtime context:
-- ALWAYS SEARCH/REPLACE for `.gts` files — never `write-text-file` (tool calls don't stream; UI freezes).
-- `write-text-file` is acceptable for `.json` instance data.
+- ALWAYS SEARCH/REPLACE — for `.gts` and `.json` files alike; avoid `write-text-file` (tool calls don't stream; UI freezes).
 - For new files, mark the URL line with `(new)`.
 
 For the full block format, matching rules, and recovery from failed matches, read the canonical skill.
diff --git a/skills/boxel-environment/references/workflows-and-orchestration.md b/skills/boxel-environment/references/workflows-and-orchestration.md
index bf7676e..9365065 100644
--- a/skills/boxel-environment/references/workflows-and-orchestration.md
+++ b/skills/boxel-environment/references/workflows-and-orchestration.md
@@ -56,7 +56,7 @@ Prompt "debug this error: ..."
 
 ### Code Generation
 ```json
-`switch-submode_dd88` with `attributes.submode` set to "code"
+`switch-submode_dd88` with `attributes.submode` set to "code" and `attributes.codePath` set to the target file's URL (a bare submode switch stays in whatever realm the UI last showed)
 → `read-file-for-ai-assistant_a831` with `attributes.fileUrl` set to "https://[domain]/user/card.gts"
 → Emit a code patch search/replace block
 → (offer refresh)
@@ -64,7 +64,7 @@ Prompt "debug this error: ..."
 
 ### Card Creation
 ```json
-`switch-submode_dd88` with `attributes.submode` set to "code"
+`switch-submode_dd88` with `attributes.submode` set to "code", `attributes.createFile` set to true, and `attributes.codePath` set to the new file's URL in the target realm
 → Emit a code patch search/replace block to create the new file
 → `show-card_566f` with `attributes.cardId` set to the url of the new file
 ```
diff --git a/skills/boxel-patterns/SKILL.md b/skills/boxel-patterns/SKILL.md
index 09857cb..234b82f 100644
--- a/skills/boxel-patterns/SKILL.md
+++ b/skills/boxel-patterns/SKILL.md
@@ -46,7 +46,7 @@ Ready patterns below can be read and adapted. Each has `patterns/<slug>/README.m
 
 - `pick-rating` — Editable star-rating FieldDef with full/half/empty read display, atom + embedded formats, and `@set(new RatingsSummary(...))` writeback.
 - `pick-typed-sort` — `SortMenu` dropdown + typed `SortOption` interface + exported `Sort` constants. Replaces ad-hoc string sort keys.
-- `attach-remote-image` *(README-only)* — Image field accepting an uploaded ImageDef OR an external URL via the pair-of-fields convention (`linksTo(ImageDef)` + URL field). **Critical:** prevents the realm-bricking external-URL-in-`links.self` bug (Cardinal Rule 13). See `boxel/references/base-field-catalog.md` "Image fields — the URL/ImageDef pair pattern".
+- `attach-remote-image` *(README-only)* — Image field accepting an uploaded ImageDef OR an external URL via the pair-of-fields convention (`linksTo(ImageDef)` + URL field). **Critical:** prevents the realm-bricking external-URL-in-`links.self` bug (Cardinal Rule 12). See `boxel/references/base-field-catalog.md` "Image fields — the URL/ImageDef pair pattern".
 
 ### Build / Template
 
diff --git a/skills/boxel-patterns/patterns/attach-remote-image/README.md b/skills/boxel-patterns/patterns/attach-remote-image/README.md
index 6255c2a..0e7c76e 100644
--- a/skills/boxel-patterns/patterns/attach-remote-image/README.md
+++ b/skills/boxel-patterns/patterns/attach-remote-image/README.md
@@ -8,7 +8,7 @@ validated: source-proven
 
 **When to use:** Any CardDef that should display an image when the author has provided one of two ways — uploaded bytes via FileDef OR an external URL. This is the pattern to reach for whenever an AI agent might be tempted to drop an Unsplash URL into a card.
 
-**Why this matters:** Putting an external URL directly into a relationship's `links.self` BRICKS the realm. The indexer fetches the URL expecting a card document, gets JPEG/PNG binary bytes, JSON.parse throws on the binary, the error message contains the binary's NULL byte, postgres rejects the JSONB write (`22P05: unsupported Unicode escape sequence`), and the entire indexing transaction rolls back — every successfully-rendered sibling card in the batch is lost. The whole realm stays unindexed until the bad instance is fixed. See `boxel/SKILL.md` Cardinal Rule 13.
+**Why this matters:** Putting an external URL directly into a relationship's `links.self` BRICKS the realm. The indexer fetches the URL expecting a card document, gets JPEG/PNG binary bytes, JSON.parse throws on the binary, the error message contains the binary's NULL byte, postgres rejects the JSONB write (`22P05: unsupported Unicode escape sequence`), and the entire indexing transaction rolls back — every successfully-rendered sibling card in the batch is lost. The whole realm stays unindexed until the bad instance is fixed. See `boxel/SKILL.md` Cardinal Rule 12.
 
 **The insight:** This is the same pair pattern base `cardInfo` already uses for thumbnails (`base/card-api.gts:2892-2893`):
 
@@ -130,7 +130,7 @@ The relationship link points at a real ImageDef instance in the realm — never
 
 ## See also
 
-- `boxel/SKILL.md` Cardinal Rule 13 — the realm-bricking failure mode this pattern prevents.
+- `boxel/SKILL.md` Cardinal Rule 12 — the realm-bricking failure mode this pattern prevents.
 - `boxel/references/base-field-catalog.md` "Image fields — the URL/ImageDef pair pattern".
 - `boxel-file-def/SKILL.md` — for uploading bytes into the realm via `WriteBinaryFileCommand` → `ImageDef`.
 - `integrate-openrouter-image-generation` — when generating images via OpenRouter, the resulting bytes become an ImageDef (linked side); use this pattern when the source could be either generated bytes OR a hand-picked external URL.
diff --git a/skills/boxel-patterns/patterns/integrate-three-js-3mf-fabrication/example.gts b/skills/boxel-patterns/patterns/integrate-three-js-3mf-fabrication/example.gts
index c84eacf..7c8a037 100644
--- a/skills/boxel-patterns/patterns/integrate-three-js-3mf-fabrication/example.gts
+++ b/skills/boxel-patterns/patterns/integrate-three-js-3mf-fabrication/example.gts
@@ -1,17 +1,15 @@
-// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══
-// @ts-expect-error Runtime ESM import is resolved by the realm. // ¹
+// @ts-expect-error Runtime ESM import is resolved by the realm.
 import * as THREE from "https://esm.sh/three@0.160.0";
-// ² Keep this import on one line so the TypeScript suppression stays attached.
+// Keep this import on one line so the TypeScript suppression stays attached.
 // prettier-ignore
 // @ts-expect-error Runtime ESM import is resolved by the realm.
 import { Brush, Evaluator, SUBTRACTION } from "https://esm.sh/three-bvh-csg@0.0.16?deps=three@0.160.0";
 
-// 🧩 PATTERN: prepare raised or flat/flush, manifold, color-mapped parts for 3MF export. // ³
+// 🧩 PATTERN: prepare raised or flat/flush, manifold, color-mapped parts for 3MF export.
 
-export type FabricationFinish = "raised" | "flush"; // ⁴
+export type FabricationFinish = "raised" | "flush";
 
 export interface FabricationSettings {
-  // ⁵
   finish: FabricationFinish;
   width: number;
   height: number;
@@ -22,7 +20,6 @@ export interface FabricationSettings {
 }
 
 export interface PrintablePart {
-  // ⁶
   name: string;
   color: string;
   mesh: THREE.Mesh;
@@ -30,29 +27,25 @@ export interface PrintablePart {
 }
 
 export interface WeldedMeshData {
-  // ⁷
   vertices: Array<readonly [number, number, number]>;
   triangles: Array<readonly [number, number, number]>;
 }
 
 export interface Prepared3MFPart extends WeldedMeshData {
-  // ⁸
   name: string;
   color: string;
   extruder: number;
 }
 
-const evaluator = new Evaluator(); // ⁹
+const evaluator = new Evaluator();
 
 function positive(value: number, label: string): void {
-  // ¹⁰
   if (!Number.isFinite(value) || value <= 0) {
     throw new Error(`${label} must be a positive finite number`);
   }
 }
 
 export function assertOrientationPreservingScale(mesh: THREE.Mesh): void {
-  // ¹¹
   mesh.updateMatrixWorld(true);
   if (mesh.matrixWorld.determinant() <= 0) {
     throw new Error(
@@ -61,7 +54,7 @@ export function assertOrientationPreservingScale(mesh: THREE.Mesh): void {
   }
 }
 
-function centeredBox( // ¹²
+function centeredBox(
   width: number,
   height: number,
   depth: number,
@@ -77,7 +70,7 @@ function centeredBox( // ¹²
  * Raised: the feature overlaps an uncut backing.
  * Flush: a deeper cutter removes the feature volume from the backing.
  */
-export function buildSampleAssembly( // ¹³
+export function buildSampleAssembly(
   settings: FabricationSettings
 ): PrintablePart[] {
   positive(settings.width, "width");
@@ -137,7 +130,7 @@ export function buildSampleAssembly( // ¹³
     surfaceZ - settings.featureDepth / 2
   );
 
-  const backingBrush = new Brush(backing.geometry); // ¹⁴
+  const backingBrush = new Brush(backing.geometry);
   backingBrush.position.copy(backing.position);
   backingBrush.updateMatrixWorld(true);
   const cutterBrush = new Brush(cutter.geometry);
@@ -163,13 +156,12 @@ export function buildSampleAssembly( // ¹³
 }
 
 function quantizedKey(point: THREE.Vector3, precision: number): string {
-  // ¹⁵
   return [point.x, point.y, point.z]
     .map((value) => Math.round(value / precision))
     .join(":");
 }
 
-export function weldedMeshData( // ¹⁶
+export function weldedMeshData(
   mesh: THREE.Mesh,
   precision = 1e-5
 ): WeldedMeshData {
@@ -225,7 +217,6 @@ export function weldedMeshData( // ¹⁶
 }
 
 export function topologyProblems(data: WeldedMeshData): string[] {
-  // ¹⁷
   const edgeUses = new Map<string, number>();
   for (const [a, b, c] of data.triangles) {
     for (const [from, to] of [
@@ -252,7 +243,7 @@ export function topologyProblems(data: WeldedMeshData): string[] {
   return problems;
 }
 
-export function assertZBounds( // ¹⁸
+export function assertZBounds(
   data: WeldedMeshData,
   expected: readonly [number, number],
   tolerance = 1e-4
@@ -272,13 +263,11 @@ export function assertZBounds( // ¹⁸
 }
 
 function normalizedColor(input: string): string {
-  // ¹⁹
   return `#${new THREE.Color(input).getHexString().toUpperCase()}`;
 }
 
 /** Return only validated data to the XML/ZIP layer. */
 export function prepare3MFInput(parts: PrintablePart[]): Prepared3MFPart[] {
-  // ²⁰
   const extruderByColor = new Map<string, number>();
 
   return parts.map((part) => {
diff --git a/skills/boxel-patterns/patterns/show-count-tiles-from-query/example.gts b/skills/boxel-patterns/patterns/show-count-tiles-from-query/example.gts
index 3d76bef..144b40e 100644
--- a/skills/boxel-patterns/patterns/show-count-tiles-from-query/example.gts
+++ b/skills/boxel-patterns/patterns/show-count-tiles-from-query/example.gts
@@ -1,4 +1,4 @@
-// ¹ Pattern example: query metadata count tiles.
+// Pattern example: query metadata count tiles.
 import {
   CardDef,
   Component,
diff --git a/skills/boxel-patterns/references/integration-surfaces.md b/skills/boxel-patterns/references/integration-surfaces.md
index ba6f66f..e02e875 100644
--- a/skills/boxel-patterns/references/integration-surfaces.md
+++ b/skills/boxel-patterns/references/integration-surfaces.md
@@ -89,18 +89,18 @@ Available only inside the running Boxel app. Each is a default-export `Command`
 | `patch-fields` | Surgical field updates on an instance (requires approval). |
 | `patch-card-instance` | Full-card replace (use sparingly). |
 | `apply-markdown-edit` | Targeted edits in long markdown fields (requires approval). |
-| `write-text-file` | Write a `.json` instance (requires approval). **Never use for `.gts`** — UI freezes. |
+| `write-text-file` | Avoid — create and edit files with SEARCH/REPLACE instead (tool calls don't stream; UI freezes). |
 | `copy-card`, `copy-source`, `copy-file-to-realm` | Duplicate a card, source file, or FileDef-backed asset (requires approval where applicable). |
 | `transform-cards` | Bulk command-applied transform (requires approval). |
 | `read-file-for-ai-assistant`, `read-card-for-ai-assistant` | Load file or card content into context. |
 | `search-cards` | `SearchCardsByQueryCommand` (advanced) and `SearchCardsByTypeAndTitleCommand` (simple). |
 | `search-google-images` | Google Custom Search image lookup through `send-request-via-proxy`; returns image/result metadata, not a stored realm file. |
 | `search-and-choose` | Search cards, ask the LLM to choose numbered options, and return selected ids/cards. Used by listing flows. |
-| `switch-submode` | Toggle interact/code modes, create-file mode. |
+| `switch-submode` | Toggle interact/code modes, create-file mode. Pass `codePath` to target a specific realm — a bare switch stays in the current realm. |
 | `show-card`, `show-file` | Display a card or source file in the current submode. |
 | `preview-format` | Open module + card preview side-by-side (code mode). |
 | `update-code-path-with-selection` | Navigate the code editor. |
-| `open-workspace` | Switch workspace by URL. |
+| `open-workspace` | Switch workspace by URL (lands in interact mode — exits code mode). |
 | `update-room-skills` | Activate / deactivate skills in the AI room. |
 | `execute-atomic-operations` | Run a transactional plan (used by listing-install). |
 | `fetch-card-json`, `get-card`, `read-source`, `serialize-card`, `validate-realm` | Realm-server primitives. |
diff --git a/skills/boxel/SKILL.md b/skills/boxel/SKILL.md
index c7ef8ef..f067dd6 100644
--- a/skills/boxel/SKILL.md
+++ b/skills/boxel/SKILL.md
@@ -18,19 +18,18 @@ You are generating idiomatic Boxel: **Card Definitions** in `.gts` (Glimmer Type
 | 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 line-1 tracking banner or `ⁿ` markers when edit-tracking mode is on. |
-| 5 | Missing `fitted` format on a CardDef. All CardDefs need `isolated`, `embedded`, AND `fitted`. |
-| 6 | **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. |
-| 7 | **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. |
-| 8 | **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. |
-| 9 | **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. |
-| 10 | **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`. |
-| 11 | **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. |
-| 12 | **`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`. |
-| 13 | **🚨 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". |
-| 14 | **🚨 `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". |
-
-> **Rules 6–8 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).
+| 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". |
+
+> **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 12 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.
 
@@ -92,7 +91,7 @@ Core syntax and patterns (load when topic comes up):
 - `references/core-patterns.md` — Card definitions, computed title, 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 SEARCH/REPLACE format and edit-tracking convention.
+- `references/file-editing.md` — Pointer to the `source-code-editing` skill, which defines the SEARCH/REPLACE format.
 - `references/data-management.md` — File organization, JSON instance format, field value patterns, relationships.
 - `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.
diff --git a/skills/boxel/references/core-patterns.md b/skills/boxel/references/core-patterns.md
index 8030b89..793a0a5 100644
--- a/skills/boxel/references/core-patterns.md
+++ b/skills/boxel/references/core-patterns.md
@@ -149,13 +149,11 @@ Beyond the cardinal rules in `SKILL.md` (contains vs linksTo, exports, three for
 
 ### 4. Templates with Proper Computation Patterns
 
-**Remember:** When implementing templates via SEARCH/REPLACE, track all major sections with ⁿ and include the post-block notation `╰ ⁿ⁻ᵐ`
-
 ```gts
-static isolated = class Isolated extends Component<typeof BlogPost> { // ³⁰ Isolated format
+static isolated = class Isolated extends Component<typeof BlogPost> { // Isolated format
   @tracked showComments = false;
   
-  // ³¹ CRITICAL: Do ALL computation in functions, never in templates
+  // CRITICAL: Do ALL computation in functions, never in templates
   get safeTitle() {
     try {
       return this.args?.model?.title ?? 'Untitled Post';
@@ -181,7 +179,7 @@ static isolated = class Isolated extends Component<typeof BlogPost> { // ³⁰ I
   }
   
   <template>
-    <!-- ³² Responsive surface that adapts from wide layouts down to mobile -->
+    <!-- Responsive surface that adapts from wide layouts down to mobile -->
     <article class="blog-post-surface">
       <header>
         <time>{{if @model.publishDate (formatDateTime @model.publishDate 'MMMM D, YYYY') "Date not set"}}</time>
@@ -204,7 +202,7 @@ static isolated = class Isolated extends Component<typeof BlogPost> { // ³⁰ I
         {{/if}}
       </div>
       
-      <!-- ³³ Handle arrays with REQUIRED spacing -->
+      <!-- Handle arrays with REQUIRED spacing -->
       {{#if (gt @model.tags.length 0)}}
         <section class="tags-section">
           <h4>Tags</h4>
@@ -244,7 +242,7 @@ static isolated = class Isolated extends Component<typeof BlogPost> { // ³⁰ I
       {{/if}}
     </article>
     
-    <style scoped> /* ³⁴ Component styles */
+    <style scoped> /* Component styles */
       .blog-post-surface {
         container-type: inline-size;
         width: 100%;
@@ -279,7 +277,7 @@ static isolated = class Isolated extends Component<typeof BlogPost> { // ³⁰ I
         line-height: 1.25;
       }
       
-      /* ³⁵ CRITICAL: Always style buttons completely - never use unstyled */
+      /* CRITICAL: Always style buttons completely - never use unstyled */
       .comment-button {
         /* Style Boxel components to match your design */
         gap: var(--boxel-sp-2xs);
@@ -290,7 +288,7 @@ static isolated = class Isolated extends Component<typeof BlogPost> { // ³⁰ I
         height: 1rem;
       }
       
-      /* ³⁶ CRITICAL: Spacing for containsMany collections */
+      /* CRITICAL: Spacing for containsMany collections */
       .tags-container > .containsMany-field {
         display: flex;
         flex-wrap: wrap;
diff --git a/skills/boxel/references/defensive-programming.md b/skills/boxel/references/defensive-programming.md
index 361474c..9bac02d 100644
--- a/skills/boxel/references/defensive-programming.md
+++ b/skills/boxel/references/defensive-programming.md
@@ -53,7 +53,7 @@ return (this.args.model?.progress ?? 0) + 10;
 When accessing data across card relationships, always wrap in try-catch to handle missing or malformed data:
 
 ```js
-// ³⁷ In computed properties or methods
+// In computed properties or methods
 get authorDisplayName() {
   try {
     const author = this.args?.model?.author;
@@ -79,7 +79,7 @@ get authorDisplayName() {
   }
 }
 
-// ³⁸ In template getters
+// In template getters
 get relatedPostsSummary() {
   try {
     const posts = this.args.model?.relatedPosts;
diff --git a/skills/boxel/references/delegated-rendering.md b/skills/boxel/references/delegated-rendering.md
index 285a29b..ca20c23 100644
--- a/skills/boxel/references/delegated-rendering.md
+++ b/skills/boxel/references/delegated-rendering.md
@@ -41,7 +41,7 @@ Regular HTML selects are limited to plain text. BoxelSelect lets you create rich
 #### Pattern: Rich Select with Custom Options
 
 ```gts
-export class OptionField extends FieldDef { // ⁴³ Option field for select
+export class OptionField extends FieldDef { // Option field for select
   static displayName = 'Option';
   
   @field key = contains(StringField);
@@ -58,10 +58,10 @@ export class OptionField extends FieldDef { // ⁴³ Option field for select
   };
 }
 
-export class ProductCategory extends CardDef { // ⁴⁴ Card using BoxelSelect
+export class ProductCategory extends CardDef { // Card using BoxelSelect
   @field selectedCategory = contains(OptionField);
   
-  static edit = class Edit extends Component<typeof this> { // ⁴⁵ Edit format
+  static edit = class Edit extends Component<typeof this> { // Edit format
     @tracked selectedOption = this.args.model?.selectedCategory;
 
     options = [
diff --git a/skills/boxel/references/file-editing.md b/skills/boxel/references/file-editing.md
index b870e59..2d3242d 100644
--- a/skills/boxel/references/file-editing.md
+++ b/skills/boxel/references/file-editing.md
@@ -1,12 +1,11 @@
 # File Editing
 
-The SEARCH/REPLACE block format and the `.gts` edit-tracking convention (line-1 banner, `// ⁿ` markers) are defined in the canonical [`source-code-editing`](../../source-code-editing/SKILL.md) skill, not here.
+The SEARCH/REPLACE block format is defined in the canonical [`source-code-editing`](../../source-code-editing/SKILL.md) skill, not here.
 
 - Trigger: any file edit or creation — imports, fields, templates, computed properties, new `.gts` files.
 
 Key reminders:
 
-- ALWAYS use SEARCH/REPLACE for `.gts` files — never `write-text-file`.
-- Every `.gts` file starts with the `// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══` banner; mark changed lines with sequential `// ⁿ` superscript comments. `.json` files never get tracking comments.
+- ALWAYS use SEARCH/REPLACE to create and edit files — `.gts` and `.json` alike; never `write-text-file`.
 - For new files, append `(new)` after the file URL line.
 - SEARCH text must match the existing file exactly; keep blocks small.
diff --git a/skills/boxel/references/imagedef.md b/skills/boxel/references/imagedef.md
index a3a5d6b..32ac383 100644
--- a/skills/boxel/references/imagedef.md
+++ b/skills/boxel/references/imagedef.md
@@ -110,4 +110,4 @@ const result = await upload.execute({
 
 - [`base-field-catalog.md`](./base-field-catalog.md) "Image fields — the URL/ImageDef pair pattern" — the pair pattern in detail.
 - [`core-concept.md`](./core-concept.md) "Relationship path resolution" — why `links.self` needs `./` / `../` / `http` prefix.
-- Cardinal Rule 13 in `CLAUDE.md` — never put external URLs in relationship `links.self`.
+- Cardinal Rule 12 in `CLAUDE.md` — never put external URLs in relationship `links.self`.
diff --git a/skills/boxel/references/lint-workflow.md b/skills/boxel/references/lint-workflow.md
index adced1f..44258b8 100644
--- a/skills/boxel/references/lint-workflow.md
+++ b/skills/boxel/references/lint-workflow.md
@@ -4,7 +4,7 @@ Linting is part of the core Boxel code workflow. Every `.gts` change needs a rea
 
 **Which context are you in?** Two execution contexts run this workflow, and they use different lint transports:
 
-- **Shell contexts** (Claude Code, a terminal, CI, any agent with Bash): use the `npx boxel` CLI commands below. This is what CLAUDE.md and `boxel/SKILL.md` Cardinal Rule 10 refer to.
+- **Shell contexts** (Claude Code, a terminal, CI, any agent with Bash): use the `npx boxel` CLI commands below. This is what CLAUDE.md and `boxel/SKILL.md` Cardinal Rule 9 refer to.
 - **The in-app Boxel AI assistant** (no shell): use `checkCorrectness` (next section). The CLI commands are unavailable there — do not attempt them.
 
 Both transports hit the same server-side lint gate; only the invocation differs.
diff --git a/skills/boxel/references/quick-reference.md b/skills/boxel/references/quick-reference.md
index c846b8e..1b9e575 100644
--- a/skills/boxel/references/quick-reference.md
+++ b/skills/boxel/references/quick-reference.md
@@ -24,11 +24,10 @@ import { formatDateTime, formatNumber, formatCurrency } from '@cardstack/boxel-u
 **Optional `markdown` Format:** A working default (HTML-to-markdown fallback) is provided; only define `static markdown` when the default output is poor — see `boxel-markdown-format`.
 
 ```gts
-// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══
-// ¹ Core imports - ALWAYS needed for definitions
+// Core imports - ALWAYS needed for definitions
 import { CardDef, FieldDef, Component, field, contains, containsMany, linksTo, linksToMany } from 'https://cardstack.com/base/card-api';
 
-// ² Base field imports (only what you use)
+// Base field imports (only what you use)
 import StringField from 'https://cardstack.com/base/string';
 import NumberField from 'https://cardstack.com/base/number';
 import BooleanField from 'https://cardstack.com/base/boolean';
@@ -40,7 +39,7 @@ import BigIntegerField from 'https://cardstack.com/base/big-integer';
 import CodeRefField from 'https://cardstack.com/base/code-ref';
 import Base64ImageField from 'https://cardstack.com/base/base64-image'; // 🚨 NEVER USE - embeds binary in JSON, crashes AI context; use FileDef types instead
 
-// ⁸ FileDef imports - for file fields (use linksTo, never contains)
+// FileDef imports - for file fields (use linksTo, never contains)
 import FileDef from 'https://cardstack.com/base/file-api';
 import ImageDef from 'https://cardstack.com/base/image-file-def';     // any image
 import PngDef from 'https://cardstack.com/base/png-image-def';        // .png
@@ -67,11 +66,11 @@ import AddressField from 'https://cardstack.com/base/address';
 // export class FancyAddressField extends BaseAddressField { }
 // Never import and define the same field name - it causes conflicts!
 
-// ³ UI Component imports
+// UI Component imports
 import { Button, Pill, Avatar, FieldContainer, CardContainer, BoxelSelect, ViewSelector, KanbanPlane, autoPlaceKanban } from '@cardstack/boxel-ui/components';
 import type { KanbanColumnConfig, KanbanPlacement } from '@cardstack/boxel-ui/components';
 
-// ⁴ Helper imports
+// Helper imports
 import { eq, gt, gte, lt, lte, and, or, not, cn, add, subtract, multiply, divide } from '@cardstack/boxel-ui/helpers';
 import { formatDateTime, formatNumber, formatCurrency, formatDuration, formatRelativeTime, optional, pick } from '@cardstack/boxel-ui/helpers';
 import { markdownEscape } from '@cardstack/boxel-ui/helpers'; // escape user-supplied strings in `static markdown` templates
@@ -92,20 +91,20 @@ import { task, restartableTask, timeout } from 'ember-concurrency'; // timeout i
 // concat/get/array/hash, Boxel UI predicates, or formatters, the import must
 // be present explicitly. See common-imports.md.
 
-// ⁶ TIMING RULE: NEVER use requestAnimationFrame
+// TIMING RULE: NEVER use requestAnimationFrame
 // - DOM timing: Use Glimmer modifiers with cleanup
 // - Async coordination: Use task/restartableTask from ember-concurrency  
 // - Delays: Use await timeout(ms) from ember-concurrency, not setTimeout
 // - NEVER `await someTask.perform()` (or `.then()` it) from outside a task — that downcasts the cancelable TaskInstance to a Promise, surfacing cancelations as unhandled `TaskCancelation` rejections. If the caller needs to await a task, the caller must itself be a task; invoke top-level tasks from a synchronous local handler bound with `{{on}}`.
 
-// ⁵ Icon imports
+// Icon imports
 import EmailIcon from '@cardstack/boxel-icons/mail';
 import PhoneIcon from '@cardstack/boxel-icons/phone';
 import RocketIcon from '@cardstack/boxel-icons/rocket';
 // Available from Lucide, Lucide Labs, and Tabler icon sets
 // NOTE: Only use for static card/field type icons, NOT in templates
 
-// ⁷ Drag/drop kanban
+// Drag/drop kanban
 // Use KanbanPlane for lane-based drag/drop boards; do not hand-roll pointer
 // drag in card templates. Persist placements by stable item id + column key +
 // sortOrder, map to KanbanPlacement.index only at render time, and render child
diff --git a/skills/boxel/references/template-syntax.md b/skills/boxel/references/template-syntax.md
index 2e5d9b3..5ef203d 100644
--- a/skills/boxel/references/template-syntax.md
+++ b/skills/boxel/references/template-syntax.md
@@ -316,8 +316,6 @@ Your templates must handle:
 {{/if}}
 ```
 
-**Remember:** When implementing templates via SEARCH/REPLACE, include tracking markers ⁿ for style blocks
-
 ### Real-World Example: Shopping List with Featured Items
 
 ```gts
diff --git a/skills/boxel/scripts/instance-correctness-scan.py b/skills/boxel/scripts/instance-correctness-scan.py
index 7ee6b73..e6cc1c0 100755
--- a/skills/boxel/scripts/instance-correctness-scan.py
+++ b/skills/boxel/scripts/instance-correctness-scan.py
@@ -25,7 +25,7 @@
 Exit code 0 = clean; 1 = one or more issues found. Pair with pre-push hooks
 or pre-commit checks.
 
-See `.claude/skills/boxel/SKILL.md` Cardinal Rules 12, 13, 14.
+See `.claude/skills/boxel/SKILL.md` Cardinal Rules 11, 12, 13.
 """
 import re
 import sys
diff --git a/skills/glossary.md b/skills/glossary.md
index f76ceac..f36b552 100644
--- a/skills/glossary.md
+++ b/skills/glossary.md
@@ -383,8 +383,8 @@ In rough priority order:
 - **Format choice = who owns the cell size.** `embedded` for lists; `fitted` for uniform tile grids.
 - **Every user-facing card goes through `design-playbook.md`.**
 - **Delegated render** — `<@fields.X />` injects host CardContainer chrome; override via `:deep()`, theme cascade, or `@displayContainer={{false}}`. → `boxel-ui-guidelines/references/delegated-render-control.md`
-- **Read before writing.** Many `.gts` files have edit-tracking markers; reading first preserves them.
-- **SEARCH/REPLACE for `.gts` edits.** Never `write-text-file` for `.gts` (UI freezes).
+- **Read before writing.** Fetch a file’s current contents before a SEARCH/REPLACE edit so the SEARCH block matches exactly.
+- **SEARCH/REPLACE for file creation and edits** — `.gts` and `.json` alike. Avoid `write-text-file` (UI freezes; skips the code-patch pipeline).
 - **One CardDef per file.** FieldDefs and helpers can co-locate.
 - **Three formats minimum.** Every CardDef ships `isolated`, `embedded`, AND `fitted`.
 
diff --git a/skills/source-code-editing/SKILL.md b/skills/source-code-editing/SKILL.md
index 27a1286..35a5e38 100644
--- a/skills/source-code-editing/SKILL.md
+++ b/skills/source-code-editing/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: source-code-editing
-description: Use when editing existing .gts or .json files via SEARCH/REPLACE blocks. Defines exact block format, matching rules, the .gts edit-tracking convention, and recovery from failed matches. Required before issuing any code edit.
+description: Use when editing existing .gts or .json files via SEARCH/REPLACE blocks. Defines exact block format, matching rules, and recovery from failed matches. Required before issuing any code edit.
 boxel:
   kind: skill
 ---
@@ -16,9 +16,9 @@ boxel:
 ## Don't use for
 
 - Writing brand-new files where the schema is still undecided. Decide the schema with `boxel` first.
-- JSON instance data — `write-text-file` and `patch-fields` are often better for `.json` (this skill is mandatory for `.gts`).
+- Surgical field updates on an existing instance — `patch-fields` is often better than rewriting the `.json`.
 
-When you infer that the user wants to make changes to the attached files, which is usually a card definition, or create new files, you must use a SEARCH/REPLACE block. For .gts files, ALWAYS use SEARCH/REPLACE — never use write-text-file for .gts. SEARCH/REPLACE blocks stream as visible text (the user sees progress), while tool calls like write-text-file do NOT stream (the UI appears frozen with "Thinking" / "Preparing tool call" while generating the full file content).
+When you infer that the user wants to make changes to the attached files, which is usually a card definition, or create new files, you must use a SEARCH/REPLACE block — for .gts and .json files alike; never use write-text-file. SEARCH/REPLACE blocks stream as visible text (the user sees progress), while tool calls like write-text-file do NOT stream (the UI appears frozen with "Thinking" / "Preparing tool call" while generating the full file content).
 
 A SEARCH/REPLACE block has 2 sections: a section of code to search for, and the code to replace it with. All code within the SEARCH will be replaced. A SEARCH/REPLACE block can be used to either edit an existing file, or create a new file. 
 
@@ -132,47 +132,3 @@ When you respond with a SEARCH/REPLACE block, do not refer to it as a SEARCH/REP
 After emitting one or more SEARCH/REPLACE blocks, the user will need to apply the changes. Therefore, end your response after emitting all your SEARCH/REPLACE blocks instead of summarizing. You will be notified when the blocks have been applied, and you can summarize the updates that have been made then.
 
 Never respond with '[Omitting previously suggested code change]', or '[Omitting previously suggested and applied code change]'. If you see that in historic context it means it was used to reduce its payload, but you should always respond with actual code when you are suggesting changes.
-
-## Edit tracking (Boxel `.gts` convention)
-
-Boxel `.gts` files carry an edit-tracking convention so changes stay visible in the source. It applies to `.gts` files only — never add tracking comments to `.json` files.
-
-**Line 1 of every `.gts` file is the tracking banner:**
-
-```gts
-// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══
-```
-
-When you create a new Boxel `.gts` file, this banner is the first line of your REPLACE section (some earlier generic examples in this document omit tracking markers; for Boxel `.gts` files in this repo, always include the banner and markers described below).
-
-**Mark every line you add or change** with a sequential superscript comment — `// ¹ description`, `// ²`, `// ³` … — continuing from the highest marker already present in the file. Keep existing markers intact when they appear in your SEARCH section (they also help make the match unique).
-
-Example creating a new file:
-
-```gts
-http://realm/recipe-card.gts (new)
-╔═══ SEARCH ════╗
-╠═══════════════╣
-// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══
-import { CardDef } from 'https://cardstack.com/base/card-api'; // ¹
-export class RecipeCard extends CardDef { // ²
-  static displayName = 'Recipe';
-}
-╚═══ REPLACE ═══╝
-```
-
-Example modifying an existing file:
-
-```gts
-https://example.com/recipe-card.gts
-╔═══ SEARCH ════╗
-export class RecipeCard extends CardDef {
-  static displayName = 'Recipe';
-  @field recipeName = contains(StringField);
-╠═══════════════╣
-export class RecipeCard extends CardDef {
-  static displayName = 'Recipe';
-  @field recipeName = contains(StringField);
-  @field servings = contains(NumberField); // ¹⁸ Added servings
-╚═══ REPLACE ═══╝
-```