diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 59e7f001c53..2012ef1f828 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -138,6 +138,16 @@ jobs:
               # shared CI-boot paths trigger it.
               - *shared
               - 'packages/bxl/**'
+              # The card-authoring skill's claims are pinned by a BXL suite
+              # that reads the skill file, so an edit to the skill has to run
+              # that suite too.
+              - 'packages/boxel-cli/plugin/skills/bxl-authoring/**'
+              # That suite also asserts the host suites the skill cites still
+              # exist. `bxl-test` runs unconditionally on main, so without
+              # these a host-only rename would merge green and redden main on
+              # a commit whose own CI never ran the failing suite.
+              - 'packages/host/tests/integration/bxl-*'
+              - 'packages/host/tests/helpers/cards/bxl-*'
             bench-amd:
               # The AMD transpiler is a runtime-common module with no
               # cross-workspace deps that affect its wall-time, so the
diff --git a/packages/boxel-cli/plugin/README.md b/packages/boxel-cli/plugin/README.md
index db087d002ef..6c79179aa1c 100644
--- a/packages/boxel-cli/plugin/README.md
+++ b/packages/boxel-cli/plugin/README.md
@@ -83,26 +83,27 @@ Authored upstream in [`cardstack/boxel-skills`](https://github.com/cardstack/box
 
 <!-- BEGIN AUTO-GENERATED: boxel-skills (run `pnpm build:skills` to update) -->
 
-_Copied from [`cardstack/boxel-skills@v0.1.0`](https://github.com/cardstack/boxel-skills/tree/v0.1.0) by_ `pnpm build:skills`. _Edit upstream, not here._
-
-| Skill                                       | Use it for                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/boxel-cli:boxel`                          | Use whenever creating, reading, or editing Boxel cards (.gts files), card instances (.json), fields, templates, queries, or anything in a Boxel realm. Required for any Boxel coding work — covers CardDef, FieldDef, contains/linksTo, templates, formats, queries, and core patterns. Companion skills - boxel-design (visual decisions), boxel-ui-guidelines (template UI), source-code-editing (SEARCH/REPLACE), boxel-environment (running the Boxel app).                                                                                                   |
-| `/boxel-cli:boxel-create-edit-cards`        | Use when choosing the right Boxel host command combination to create new cards or edit existing instances from the AI assistant.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `/boxel-cli:boxel-design`                   | Use when DECIDING a Boxel card's visual language — mood, palette, typography direction, asset direction, one visual signature, the design-playbook process. This is the taste/decision layer. NOT for implementing tokens or CSS inside templates (that's boxel-ui-guidelines) and NOT for creating/editing Theme, StyleReference, or BrandGuide card artifacts (that's boxel-theme-development).                                                                                                                                                                 |
-| `/boxel-cli:boxel-environment`              | Use when running, navigating, or orchestrating tasks inside the live Boxel application — switching between Code Mode and Interact Mode, calling host commands (search-cards, switch-submode, show-card, patch-fields, apply-markdown-edit, reindex, etc.), or any operation that drives the Boxel UI. Activates for Boxel-app runtime work, not for writing card definitions (see boxel for that).                                                                                                                                                                |
-| `/boxel-cli:boxel-file-def`                 | Use when adding or working with file-typed fields (FileDef, ImageDef, MarkdownDef, PngDef, CsvFileDef). Activates when a card needs to reference an image, document, or other file asset.                                                                                                                                                                                                                                                                                                                                                                         |
-| `/boxel-cli:boxel-flavored-markdown`        | Use when authoring or editing Boxel Flavored Markdown (BFM) content — content fields rendered as rich markdown with :card/::card directives, mermaid diagrams, etc.                                                                                                                                                                                                                                                                                                                                                                                               |
-| `/boxel-cli:boxel-markdown-format`          | Use when authoring a `markdown` template (static markdown format) on a CardDef or FieldDef — defaults, markdownEscape, and markdown helpers.                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `/boxel-cli:boxel-patterns`                 | Use when the user names an outcome ("show a chart", "let users pick a color", "build a dashboard", "summarize comments", "embed AI image generation", "lay out a moodboard") and you need a working code example to start from. This skill is the bridge between user intent and the existing patterns in Boxel realms. Index your search by what the user wants to DO, not by which CardDef/FieldDef class to extend. Activates when the user asks "do we have a pattern for…", "how is X typically done", or names a feature outcome that isn't in core syntax. |
-| `/boxel-cli:boxel-skill-authoring`          | Use when creating or editing a user-authored Boxel skill — a markdown file whose `boxel.kind: skill` frontmatter makes it loadable by AI assistant rooms. Covers the SKILL.md format contract, the frontmatter schema, tool declarations (codeRef forms, requiresApproval), placement conventions, and how to verify the skill indexed correctly. Activates for "write me a skill", "add a tool to my skill", or a skill that isn't showing up in the skill chooser.                                                                                              |
-| `/boxel-cli:boxel-theme-development`        | Use when the deliverable is a theme ARTIFACT — creating, converting, auditing, or patching Theme, StructuredTheme, StyleReference, DetailedStyleReference, or BrandGuide cards; importing/exporting Google DESIGN.md design-system briefs; logo/mark usage and functional palettes. NOT for deciding a card's visual language (boxel-design) and NOT for applying tokens inside card templates (boxel-ui-guidelines).                                                                                                                                             |
-| `/boxel-cli:boxel-ui-component-discovery`   | MANDATORY before writing any UI in a `.gts` template. Search the catalog for a boxel-ui component Spec and reuse it. Fall back to raw HTML only when no matching spec exists, and surface the gap when you do.                                                                                                                                                                                                                                                                                                                                                    |
-| `/boxel-cli:boxel-ui-guidelines`            | Use when IMPLEMENTING UI in Boxel templates — applying var(--\*) theme tokens in <style scoped>, choosing between @fields and @model, using boxel-ui components (Button, Pill, Avatar, BoxelSelect), controlling embedded-card chrome, or fixing layout/overflow issues. This is the template-implementation layer. Visual-language decisions belong to boxel-design; the Theme card artifact itself belongs to boxel-theme-development.                                                                                                                          |
-| `/boxel-cli:boxel-workspace-cardinal-rules` | Silent-failure traps in Boxel card authoring — rules that pass lint and often indexing, then corrupt the realm index, crash at render, or drop data with no error (DateField vs DateTimeField formats, external URLs in relationship links, and more). Check every card and field against this list before finishing.                                                                                                                                                                                                                                             |
-| `/boxel-cli:catalog-listing`                | Use when installing, browsing, remixing, updating, or submitting catalog listings (Apps, Cards, Fields, Skills, Themes) from a Boxel catalog realm. Includes the submission workflow that creates a SubmissionWorkflowCard and GitHub PR.                                                                                                                                                                                                                                                                                                                         |
-| `/boxel-cli:ember-best-practices`           | Ember.js performance optimization and accessibility guidelines. This skill should be used when writing, reviewing, or refactoring Ember.js code to ensure optimal performance patterns and accessibility. Triggers on tasks involving Ember components, routes, data fetching, bundle optimization, or accessibility improvements.                                                                                                                                                                                                                                |
-| `/boxel-cli:source-code-editing`            | 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.                                                                                                                                                                                                                                                                                                                                                                     |
+_Copied from [`cardstack/boxel-skills@v0.1.1`](https://github.com/cardstack/boxel-skills/tree/v0.1.1) by_ `pnpm build:skills`. _Edit upstream, not here._
+
+| Skill                                       | Use it for                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/boxel-cli:boxel`                          | Use whenever creating, reading, or editing Boxel cards (.gts files), card instances (.json), fields, templates, queries, or anything in a Boxel realm. Required for any Boxel coding work — covers CardDef, FieldDef, contains/linksTo, templates, formats, queries, and core patterns. Companion skills - boxel-design (visual decisions), boxel-ui-guidelines (template UI), source-code-editing (SEARCH/REPLACE), boxel-environment (running the Boxel app).                                                                                                                                                              |
+| `/boxel-cli:boxel-create-edit-cards`        | Use when choosing the right Boxel host command combination to create new cards or edit existing instances from the AI assistant.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `/boxel-cli:boxel-design`                   | Use when DECIDING a Boxel card's visual language — mood, palette, typography direction, asset direction, one visual signature, the design-playbook process. This is the taste/decision layer. NOT for implementing tokens or CSS inside templates (that's boxel-ui-guidelines) and NOT for creating/editing Theme, StyleReference, or BrandGuide card artifacts (that's boxel-theme-development).                                                                                                                                                                                                                            |
+| `/boxel-cli:boxel-environment`              | Use when running, navigating, or orchestrating tasks inside the live Boxel application — switching between Code Mode and Interact Mode, calling host commands (search-cards, switch-submode, show-card, patch-fields, apply-markdown-edit, reindex, etc.), or any operation that drives the Boxel UI. Activates for Boxel-app runtime work, not for writing card definitions (see boxel for that).                                                                                                                                                                                                                           |
+| `/boxel-cli:boxel-file-def`                 | Use when adding or working with file-typed fields (FileDef, ImageDef, MarkdownDef, PngDef, CsvFileDef). Activates when a card needs to reference an image, document, or other file asset.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `/boxel-cli:boxel-flavored-markdown`        | Use when authoring or editing Boxel Flavored Markdown (BFM) content — content fields rendered as rich markdown with :card/::card directives, mermaid diagrams, etc.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `/boxel-cli:boxel-markdown-format`          | Use when authoring a `markdown` template (static markdown format) on a CardDef or FieldDef — defaults, markdownEscape, and markdown helpers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `/boxel-cli:boxel-patterns`                 | Use when the user names an outcome ("show a chart", "let users pick a color", "build a dashboard", "summarize comments", "embed AI image generation", "lay out a moodboard") and you need a working code example to start from. This skill is the bridge between user intent and the existing patterns in Boxel realms. Index your search by what the user wants to DO, not by which CardDef/FieldDef class to extend. Activates when the user asks "do we have a pattern for…", "how is X typically done", or names a feature outcome that isn't in core syntax.                                                            |
+| `/boxel-cli:boxel-skill-authoring`          | Use when creating or editing a user-authored Boxel skill — a markdown file whose `boxel.kind: skill` frontmatter makes it loadable by AI assistant rooms. Covers the SKILL.md format contract, the frontmatter schema, tool declarations (codeRef forms, requiresApproval), placement conventions, and how to verify the skill indexed correctly. Activates for "write me a skill", "add a tool to my skill", or a skill that isn''t showing up in the skill chooser.                                                                                                                                                        |
+| `/boxel-cli:boxel-theme-development`        | Use when the deliverable is a theme ARTIFACT — creating, converting, auditing, or patching Theme, StructuredTheme, StyleReference, DetailedStyleReference, or BrandGuide cards; importing/exporting Google DESIGN.md design-system briefs; logo/mark usage and functional palettes. NOT for deciding a card's visual language (boxel-design) and NOT for applying tokens inside card templates (boxel-ui-guidelines).                                                                                                                                                                                                        |
+| `/boxel-cli:boxel-ui-component-discovery`   | MANDATORY before writing any UI in a `.gts` template. Search the catalog for a boxel-ui component Spec and reuse it. Fall back to raw HTML only when no matching spec exists, and surface the gap when you do.                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `/boxel-cli:boxel-ui-guidelines`            | Use when IMPLEMENTING UI in Boxel templates — applying var(--\*) theme tokens in <style scoped>, choosing between @fields and @model, using boxel-ui components (Button, Pill, Avatar, BoxelSelect), controlling embedded-card chrome, or fixing layout/overflow issues. This is the template-implementation layer. Visual-language decisions belong to boxel-design; the Theme card artifact itself belongs to boxel-theme-development.                                                                                                                                                                                     |
+| `/boxel-cli:boxel-workspace-cardinal-rules` | Silent-failure traps in Boxel card authoring — rules that pass lint and often indexing, then corrupt the realm index, crash at render, or drop data with no error (DateField vs DateTimeField formats, external URLs in relationship links, and more). Check every card and field against this list before finishing.                                                                                                                                                                                                                                                                                                        |
+| `/boxel-cli:bxl-authoring`                  | Use when writing or reviewing a BXL expression in a Boxel card — a computeVia built from expression(), the fx / jq tags, spreadsheet-formula fields, aggregations over linked or query-backed collections. Covers which tag to reach for, what the derive profile refuses outright, the silent traps (a stream where an aggregate was meant, jq interpolation in a plain string, & on a blank field, dates and "today"), and why an indexed computed can differ from the one the viewer sees. Activates on expression(, fx`…`, jq`…`, "BXL", "formula field", "computed field with Excel functions", "sum the linked cards". |
+| `/boxel-cli:catalog-listing`                | Use when installing, browsing, remixing, updating, or submitting catalog listings (Apps, Cards, Fields, Skills, Themes) from a Boxel catalog realm. Includes the submission workflow that creates a SubmissionWorkflowCard and GitHub PR.                                                                                                                                                                                                                                                                                                                                                                                    |
+| `/boxel-cli:ember-best-practices`           | Ember.js performance optimization and accessibility guidelines. This skill should be used when writing, reviewing, or refactoring Ember.js code to ensure optimal performance patterns and accessibility. Triggers on tasks involving Ember components, routes, data fetching, bundle optimization, or accessibility improvements.                                                                                                                                                                                                                                                                                           |
+| `/boxel-cli:source-code-editing`            | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 <!-- END AUTO-GENERATED: boxel-skills -->
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-design/SKILL.md b/packages/boxel-cli/plugin/skills/boxel-design/SKILL.md
index a5954e26763..8fc341fbad9 100644
--- a/packages/boxel-cli/plugin/skills/boxel-design/SKILL.md
+++ b/packages/boxel-cli/plugin/skills/boxel-design/SKILL.md
@@ -24,7 +24,7 @@ Read it in full before any user-facing card design. This skill (`boxel-design`)
 
 Choose the governing style source before stage 1:
 
-- **Boxel built-in feature work:** use the built-in Boxel Brand Guide as the style guide (`https://cardstack.com/base/Theme/boxel-brand-guide`). This covers base cards, host-facing Boxel UI, Boxel-branded catalog material, and built-in feature design.
+- **Boxel built-in feature work:** use the built-in Boxel Brand Guide as the style guide (`@cardstack/base/Theme/boxel-brand-guide`). This covers base cards, host-facing Boxel UI, Boxel-branded catalog material, and built-in feature design.
 - **User/custom realm work:** derive or choose the Theme/StyleReference/BrandGuide from the user's domain and content. Do not default to Boxel branding unless the user asks for Boxel-branded output.
 - **Logo, mark, or official brand material needed:** use a `BrandGuide`; its `markUsage`, `brandColorPalette`, `functionalPalette`, typography, voice, and quality standards are the source. Do not invent logo URLs or store them as miscellaneous string fields.
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-environment/SKILL.md b/packages/boxel-cli/plugin/skills/boxel-environment/SKILL.md
index 26214743841..6af23e5b9b2 100644
--- a/packages/boxel-cli/plugin/skills/boxel-environment/SKILL.md
+++ b/packages/boxel-cli/plugin/skills/boxel-environment/SKILL.md
@@ -9,6 +9,12 @@ boxel:
 
 You are the orchestrator of the Boxel AI Assistant. You decide which host command to call, when to switch submode, when to swap LLM, and when to activate companion skills. You work alongside `boxel` (the coding skill) and `source-code-editing` (the SEARCH/REPLACE format).
 
+## 🚨 Read this before planning anything
+
+**[`references/host-commands-reference.md`](references/host-commands-reference.md) is where the host commands come from — not this file.** Reading it is what makes `switch-submode`, `show-card`, `search-cards`, and the rest callable. Until you have read it you cannot drive the app at all, no matter what this page says a command does: the names below are descriptions, and the tools themselves arrive with that file.
+
+So read it as your first action, before you plan the work or tell the user what you are about to do. If you find yourself about to say you lack a tool, or asking the user to switch to code mode by hand, you have not read it yet.
+
 ---
 
 ## ⚠️ Master Decision Tree
@@ -41,6 +47,7 @@ You are the orchestrator of the Boxel AI Assistant. You decide which host comman
   └─ NO → activate via update-room-skills_3875
 → Need file content? read-file-for-ai-assistant
 → Use SEARCH/REPLACE. For NEW files: add "(new)" after the URL in the SEARCH/REPLACE block.
+→ Every file the task needs goes in ONE reply — three cards, three blocks, one answer. Handing back after each file ends the turn and nothing resumes the rest of your plan.
 → For code-change intent, ALWAYS use SEARCH/REPLACE. Data/document commands are secondary.
 → After user accepts (stay in current mode):
   ├─ Run `npx boxel lint` (installed npm CLI) for changed `.gts` files (`boxel/references/lint-workflow.md`)
@@ -62,7 +69,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:** 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.
+> **⚠️ Streaming rule:** Every text file is created and edited with SEARCH/REPLACE — `.gts`, `.json`, `.md`, `README`, all of them — adding `(new)` after the URL to create one. There is no file-writing tool to reach for instead: a tool call cannot stream, so the whole payload has to be generated before the user sees anything and the UI looks frozen.
 
 ### Step 5 — Search / find
 
@@ -105,27 +112,27 @@ Full create/edit tool tables, file naming, and path rules: `references/card-tool
 
 Batch your reads: fetch the always-relevant set in one multi-file read when this skill activates, and pull by-task references the same way — everything you know you need in one go, not one or two per turn.
 
-Always-relevant:
-- `references/assistant-persona.md` — Communication style. Concise, intent-based responses.
-- `references/calling-commands.md` — JSON structure for all tool calls. Required before any command execution.
-- `references/user-environment-awareness.md` — Parse workspace, mode, open cards from each message.
-- `references/host-commands-reference.md` — Full catalog of every host command, what it does, approval rules.
+Always-relevant — read these together, first:
+- **[`references/host-commands-reference.md`](references/host-commands-reference.md)** — **the host commands themselves.** Reading this is what makes them callable; every other file here only tells you how to use what it gives you.
+- [`references/calling-commands.md`](references/calling-commands.md) — JSON structure for all tool calls. Required before any command execution.
+- [`references/assistant-persona.md`](references/assistant-persona.md) — Communication style. Concise, intent-based responses.
+- [`references/user-environment-awareness.md`](references/user-environment-awareness.md) — Parse workspace, mode, open cards from each message.
 
 By task:
-- `references/choosing-llm-models.md` — Model selection. Check when code tasks detected or debugging stuck.
-- `references/searching-and-querying.md` — Query syntax for finding cards.
-- `references/workflows-and-orchestration.md` — Multi-step patterns (migrations, bulk operations).
-- `references/markdown-edit.md` — Editing long markdown fields surgically.
-- `../boxel/references/lint-workflow.md` — Required installed npm `boxel` lint gate for `.gts` code tasks.
+- [`references/choosing-llm-models.md`](references/choosing-llm-models.md) — Model selection. Check when code tasks detected or debugging stuck.
+- [`references/searching-and-querying.md`](references/searching-and-querying.md) — Query syntax for finding cards.
+- [`references/workflows-and-orchestration.md`](references/workflows-and-orchestration.md) — Multi-step patterns (migrations, bulk operations).
+- [`references/markdown-edit.md`](references/markdown-edit.md) — Editing long markdown fields surgically.
+- [`../boxel/references/lint-workflow.md`](../boxel/references/lint-workflow.md) — Required installed npm `boxel` lint gate for `.gts` code tasks.
 
 Troubleshooting:
-- `references/common-errors.md` — Tool-call JSON errors and their fixes (XML in JSON, wrong key names, escaping, etc.).
+- [`references/common-errors.md`](references/common-errors.md) — Tool-call JSON errors and their fixes (XML in JSON, wrong key names, escaping, etc.).
 
 Specialty:
-- `references/indexing-operations.md` — Realm reindexing commands.
-- `references/fresh-realm-push-integrity.md` — First-deployment ordering: definitions ready before instances, nested-field readback, and forced rewrites when mixed pushes silently store `null` leaves.
-- `references/diagnosing-broken-links.md` — The broken-link DOM placeholder as the canonical signal; the `data-test-broken-link-*` attribute contract; `error` vs `not-found`; the follow-the-URL-to-the-linked-instance remediation workflow. (Card-author side: `boxel/references/defensive-link-traversal.md`.)
-- `references/source-code-editing.md` — Cross-link to the SEARCH/REPLACE skill.
+- [`references/indexing-operations.md`](references/indexing-operations.md) — Realm reindexing commands.
+- [`references/fresh-realm-push-integrity.md`](references/fresh-realm-push-integrity.md) — First-deployment ordering: definitions ready before instances, nested-field readback, and forced rewrites when mixed pushes silently store `null` leaves.
+- [`references/diagnosing-broken-links.md`](references/diagnosing-broken-links.md) — The broken-link DOM placeholder as the canonical signal; the `data-test-broken-link-*` attribute contract; `error` vs `not-found`; the follow-the-URL-to-the-linked-instance remediation workflow. (Card-author side: `boxel/references/defensive-link-traversal.md`.)
+- [`references/source-code-editing.md`](references/source-code-editing.md) — Cross-link to the SEARCH/REPLACE skill.
 
 ## Sibling skills
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-environment/references/host-commands-reference.md b/packages/boxel-cli/plugin/skills/boxel-environment/references/host-commands-reference.md
index 1ac0779fbbe..ee869f87933 100644
--- a/packages/boxel-cli/plugin/skills/boxel-environment/references/host-commands-reference.md
+++ b/packages/boxel-cli/plugin/skills/boxel-environment/references/host-commands-reference.md
@@ -40,10 +40,6 @@ boxel:
         module: '@cardstack/boxel-host/tools/update-code-path-with-selection'
         name: default
       requiresApproval: false
-    - codeRef:
-        module: '@cardstack/boxel-host/tools/write-text-file'
-        name: default
-      requiresApproval: true
     - codeRef:
         module: '@cardstack/boxel-host/tools/copy-card'
         name: default
@@ -69,7 +65,7 @@ Quick lookup of every command available to this skill, what it does, and notable
 ## Editing
 
 - **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.
+- There is no file-writing tool. Every text file — `.gts`, `.json`, `.md`, `README`, anything — is written with SEARCH/REPLACE, adding `(new)` after the URL to create one. A tool call cannot stream, so the UI sits frozen through a long generation and the write skips the code-patch pipeline; SEARCH/REPLACE streams as it is produced and goes through lint and correctness checks.
 - `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).
@@ -110,4 +106,4 @@ Quick lookup of every command available to this skill, what it does, and notable
 ## Approval requirements
 
 The following require user approval before execution:
-- `transform-cards`, `write-text-file`, `copy-card`, `copy-source`, `patch-fields`, `apply-markdown-edit`
+- `transform-cards`, `copy-card`, `copy-source`, `patch-fields`, `apply-markdown-edit`
diff --git a/packages/boxel-cli/plugin/skills/boxel-environment/references/indexing-operations.md b/packages/boxel-cli/plugin/skills/boxel-environment/references/indexing-operations.md
index 0362775ccc5..3ab15183554 100644
--- a/packages/boxel-cli/plugin/skills/boxel-environment/references/indexing-operations.md
+++ b/packages/boxel-cli/plugin/skills/boxel-environment/references/indexing-operations.md
@@ -151,7 +151,7 @@ Sample command from the shell:
 expected=$(find <kit-dir> -name "*.json" -not -path "*/Theme/*" -not -name "_*" | wc -l)
 # Currently indexed CardDef instances
 indexed=$(npx boxel search --realm <url> --query \
-  '{"filter":{"type":{"module":"https://cardstack.com/base/card-api","name":"CardDef"}}}' --json \
+  '{"filter":{"type":{"module":"@cardstack/base/card-api","name":"CardDef"}}}' --json \
   | jq '.data | length')
 echo "$indexed / $expected indexed"
 ```
diff --git a/packages/boxel-cli/plugin/skills/boxel-environment/references/user-environment-awareness.md b/packages/boxel-cli/plugin/skills/boxel-environment/references/user-environment-awareness.md
index b5ca64121b8..2865f4fd42a 100644
--- a/packages/boxel-cli/plugin/skills/boxel-environment/references/user-environment-awareness.md
+++ b/packages/boxel-cli/plugin/skills/boxel-environment/references/user-environment-awareness.md
@@ -14,15 +14,15 @@ When user has multiple open cards, the navigation stack provides context:
 const openCardStack = [
   'https://app.boxel.ai/user/BlogApp',
   'https://app.boxel.ai/user/BlogPost/1',
-  'https://cardstack.com/base/Author/jane'  // May be read-only realm
+  '@cardstack/base/Author/jane'  // May be read-only realm
 ];
 
 const currentCard = openCardStack[openCardStack.length - 1];
-const navigationPath = openCardStack.map(url => url.split('/').pop());
+const navigationPath = openCardStack.map(id => id.split('/').pop());
 // → ['BlogApp', '1', 'jane']
 ```
 
-Use stack URLs to fetch card details and understand user's exploration path.
+Use stack ids to fetch card details and understand user's exploration path.
 
 
 ## Location Parsing
diff --git a/packages/boxel-cli/plugin/skills/boxel-file-def/references/import-paths.md b/packages/boxel-cli/plugin/skills/boxel-file-def/references/import-paths.md
index 607bf0ec6ad..bb1e2eca7a5 100644
--- a/packages/boxel-cli/plugin/skills/boxel-file-def/references/import-paths.md
+++ b/packages/boxel-cli/plugin/skills/boxel-file-def/references/import-paths.md
@@ -1,24 +1,24 @@
 ## Import Paths
 
 ```gts
-import FileDef from 'https://cardstack.com/base/file-api';
+import FileDef from '@cardstack/base/file-api';
 
 // Image types
-import ImageDef from 'https://cardstack.com/base/image-file-def';
-import PngDef from 'https://cardstack.com/base/png-image-def';
-import JpgDef from 'https://cardstack.com/base/jpg-image-def';
-import SvgDef from 'https://cardstack.com/base/svg-image-def';
-import GifDef from 'https://cardstack.com/base/gif-image-def';
-import WebpDef from 'https://cardstack.com/base/webp-image-def';
-import AvifDef from 'https://cardstack.com/base/avif-image-def';
+import ImageDef from '@cardstack/base/image-file-def';
+import PngDef from '@cardstack/base/png-image-def';
+import JpgDef from '@cardstack/base/jpg-image-def';
+import SvgDef from '@cardstack/base/svg-image-def';
+import GifDef from '@cardstack/base/gif-image-def';
+import WebpDef from '@cardstack/base/webp-image-def';
+import AvifDef from '@cardstack/base/avif-image-def';
 
 // Document / text types
-import MarkdownDef from 'https://cardstack.com/base/markdown-file-def';
-import TextFileDef from 'https://cardstack.com/base/text-file-def';
-import TsFileDef from 'https://cardstack.com/base/ts-file-def';
-import GtsFileDef from 'https://cardstack.com/base/gts-file-def';
-import JsonFileDef from 'https://cardstack.com/base/json-file-def';
-import CsvFileDef from 'https://cardstack.com/base/csv-file-def';
+import MarkdownDef from '@cardstack/base/markdown-file-def';
+import TextFileDef from '@cardstack/base/text-file-def';
+import TsFileDef from '@cardstack/base/ts-file-def';
+import GtsFileDef from '@cardstack/base/gts-file-def';
+import JsonFileDef from '@cardstack/base/json-file-def';
+import CsvFileDef from '@cardstack/base/csv-file-def';
 ```
 
 ### Named vs default export
@@ -26,11 +26,11 @@ import CsvFileDef from 'https://cardstack.com/base/csv-file-def';
 Most FileDef subtypes are **default-exported** (`import ImageDef from ...`). A few are **named-exported** — confirmed from the monorepo + live realm checks:
 
 ```ts
-import { MarkdownDef } from 'https://cardstack.com/base/markdown-file-def';
-import { SvgDef }      from 'https://cardstack.com/base/svg-image-def';
-import { PngDef }      from 'https://cardstack.com/base/png-image-def';
-import { CsvFileDef }  from 'https://cardstack.com/base/csv-file-def';
-import { TextFileDef } from 'https://cardstack.com/base/text-file-def';
+import { MarkdownDef } from '@cardstack/base/markdown-file-def';
+import { SvgDef }      from '@cardstack/base/svg-image-def';
+import { PngDef }      from '@cardstack/base/png-image-def';
+import { CsvFileDef }  from '@cardstack/base/csv-file-def';
+import { TextFileDef } from '@cardstack/base/text-file-def';
 ```
 
 If the import compiles but the linked field resolves to `undefined` at render time, swap default ↔ named — that's the usual fix.
diff --git a/packages/boxel-cli/plugin/skills/boxel-file-def/references/markdowndef-vs-markdownfield.md b/packages/boxel-cli/plugin/skills/boxel-file-def/references/markdowndef-vs-markdownfield.md
index 640346dc8b5..1e2b3cca724 100644
--- a/packages/boxel-cli/plugin/skills/boxel-file-def/references/markdowndef-vs-markdownfield.md
+++ b/packages/boxel-cli/plugin/skills/boxel-file-def/references/markdowndef-vs-markdownfield.md
@@ -5,7 +5,7 @@ These are completely different and are **not interchangeable**:
 |                          | `MarkdownDef`                                                                   | `MarkdownField`                                                             |
 | ------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
 | **Kind**                 | FileDef — a `.md` file in the realm                                             | FieldDef — inline text stored in the card's JSON                            |
-| **Import**               | `https://cardstack.com/base/markdown-file-def`                                  | `https://cardstack.com/base/markdown`                                       |
+| **Import**               | `@cardstack/base/markdown-file-def`                                  | `@cardstack/base/markdown`                                       |
 | **Declaration**          | `@field notes = linksTo(MarkdownDef)`                                           | `@field notes = contains(MarkdownField)`                                    |
 | **Stored as**            | Separate `.md` file referenced by URL                                           | String embedded in the card's `.json`                                       |
 | **Has own URL?**         | ✅ Yes — shareable and reusable                                                 | ❌ No — owned by the containing card                                        |
diff --git a/packages/boxel-cli/plugin/skills/boxel-file-def/references/no-inline-binary.md b/packages/boxel-cli/plugin/skills/boxel-file-def/references/no-inline-binary.md
index 3ecbd2c1d00..9a56dee5c9c 100644
--- a/packages/boxel-cli/plugin/skills/boxel-file-def/references/no-inline-binary.md
+++ b/packages/boxel-cli/plugin/skills/boxel-file-def/references/no-inline-binary.md
@@ -29,7 +29,7 @@ For AI image APIs that return a `data:image/...;base64,...`, strip the `data:mim
 
 ```gts
 import WriteBinaryFileCommand from '@cardstack/boxel-host/tools/write-binary-file';
-import { ImageDef, linksTo } from 'https://cardstack.com/base/card-api';
+import { ImageDef, linksTo } from '@cardstack/base/card-api';
 
 @field generatedImage = linksTo(ImageDef);
 
@@ -57,7 +57,7 @@ This is the same host-command family used by `packages/host/app/tools/screenshot
 `realms-staging.stack.cards/ctse/personal/a-million-dreams-karaoke.gts` handles MP3 and cover art correctly:
 
 ```gts
-import { FileDef, ImageDef, linksTo } from 'https://cardstack.com/base/card-api';
+import { FileDef, ImageDef, linksTo } from '@cardstack/base/card-api';
 
 @field mp3FileDef = linksTo(FileDef);
 @field coverArt = linksTo(ImageDef);
diff --git a/packages/boxel-cli/plugin/skills/boxel-file-def/references/using-filedef-in-cards.md b/packages/boxel-cli/plugin/skills/boxel-file-def/references/using-filedef-in-cards.md
index 1ca0acb66e1..96ffe1ebff8 100644
--- a/packages/boxel-cli/plugin/skills/boxel-file-def/references/using-filedef-in-cards.md
+++ b/packages/boxel-cli/plugin/skills/boxel-file-def/references/using-filedef-in-cards.md
@@ -1,11 +1,11 @@
 ## Using FileDef in Cards
 
 ```gts
-import { CardDef, field, linksTo } from 'https://cardstack.com/base/card-api';
-import ImageDef from 'https://cardstack.com/base/image-file-def';
-import PngDef from 'https://cardstack.com/base/png-image-def';
-import FileDef from 'https://cardstack.com/base/file-api';
-import MarkdownDef from 'https://cardstack.com/base/markdown-file-def';
+import { CardDef, field, linksTo } from '@cardstack/base/card-api';
+import ImageDef from '@cardstack/base/image-file-def';
+import PngDef from '@cardstack/base/png-image-def';
+import FileDef from '@cardstack/base/file-api';
+import MarkdownDef from '@cardstack/base/markdown-file-def';
 
 export class ProductListing extends CardDef {
   @field photo = linksTo(PngDef); // Specifically PNG
@@ -20,7 +20,7 @@ export class ProductListing extends CardDef {
 The A Million Dreams karaoke card keeps a multi-megabyte MP3 out of card JSON by linking to the realm file:
 
 ```gts
-import { FileDef, ImageDef, linksTo } from 'https://cardstack.com/base/card-api';
+import { FileDef, ImageDef, linksTo } from '@cardstack/base/card-api';
 
 @field mp3FileDef = linksTo(FileDef);
 @field coverArt = linksTo(ImageDef);
@@ -49,7 +49,7 @@ When generated media arrives as a `data:image/...;base64,...`, write it to the r
 
 ```gts
 import WriteBinaryFileCommand from '@cardstack/boxel-host/tools/write-binary-file';
-import { ImageDef, linksTo } from 'https://cardstack.com/base/card-api';
+import { ImageDef, linksTo } from '@cardstack/base/card-api';
 
 @field outputImage = linksTo(ImageDef);
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/shape-of-a-static-markdown-template.md b/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/shape-of-a-static-markdown-template.md
index 30e5ee2df21..93732e0726b 100644
--- a/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/shape-of-a-static-markdown-template.md
+++ b/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/shape-of-a-static-markdown-template.md
@@ -3,7 +3,7 @@
 It's a format slot like `static isolated`, but emits **plain text**, not HTML. Glimmer HTML-escapes the string in the DOM; the prerender pipeline decodes those entities when it captures `textContent`, so the markdown parser downstream sees the literal characters you emitted.
 
 ```gts
-import { CardDef, Component } from 'https://cardstack.com/base/card-api';
+import { CardDef, Component } from '@cardstack/base/card-api';
 import { markdownEscape } from '@cardstack/boxel-ui/helpers';
 
 export class Note extends CardDef {
diff --git a/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/the-markdown-helpers-toolkit.md b/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/the-markdown-helpers-toolkit.md
index a1f7d8c1e7f..32392f841c7 100644
--- a/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/the-markdown-helpers-toolkit.md
+++ b/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/the-markdown-helpers-toolkit.md
@@ -1,6 +1,6 @@
 ## The `markdown-helpers` toolkit
 
-Module: `https://cardstack.com/base/markdown-helpers`
+Module: `@cardstack/base/markdown-helpers`
 
 ```gts
 import {
@@ -14,7 +14,7 @@ import {
   markdownLinksForCards,
   markdownEmbedForCard,
   markdownEmbedsForCards,
-} from 'https://cardstack.com/base/markdown-helpers';
+} from '@cardstack/base/markdown-helpers';
 ```
 
 All helpers return pre-escaped strings — safe to interpolate directly.
diff --git a/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/worked-example-note-card-with-custom-markdown.md b/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/worked-example-note-card-with-custom-markdown.md
index 688e39180bb..71d5548b4de 100644
--- a/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/worked-example-note-card-with-custom-markdown.md
+++ b/packages/boxel-cli/plugin/skills/boxel-markdown-format/references/worked-example-note-card-with-custom-markdown.md
@@ -1,11 +1,11 @@
 ## Worked example: `Note` card with custom markdown
 
 ```gts
-import { CardDef, field, contains, linksTo, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import MarkdownField from 'https://cardstack.com/base/markdown';
+import { CardDef, field, contains, linksTo, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import MarkdownField from '@cardstack/base/markdown';
 import { markdownEscape } from '@cardstack/boxel-ui/helpers';
-import { markdownLinkForCard, formatDateTimeForMarkdown } from 'https://cardstack.com/base/markdown-helpers';
+import { markdownLinkForCard, formatDateTimeForMarkdown } from '@cardstack/base/markdown-helpers';
 import { Author } from './author';
 
 export class Note extends CardDef {
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/SKILL.md b/packages/boxel-cli/plugin/skills/boxel-patterns/SKILL.md
index 334069ea529..ede2e4ee274 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/SKILL.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/SKILL.md
@@ -146,7 +146,7 @@ For every import path and every integration surface:
 
 - **`references/integration-surfaces.md`** — Capability-dimension cheatsheet. 10 sections covering base Card APIs, runtime APIs, host commands, Boxel UI, Ember/Glimmer tools, realm-bundled libraries, AI services, ESM CDN libraries, BFM features, and boxel-cli commands. Use this when planning what a card can reach for.
 - **`references/libraries.md`** — Import-path-dimension catalogue. Three portable tiers:
-  - **Tier 1** — Boxel base (URL-pinned, `https://cardstack.com/base/...`).
+  - **Tier 1** — Boxel base (`@cardstack/base/...`).
   - **Tier 2** — npm (`@cardstack/*`, `@ember/*`, `@glimmer/*`, `ember-*`).
   - **Tier 4** — ESM CDN (`https://esm.run/three`, `https://esm.sh/leaflet`, etc.).
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/app-card-home-with-search/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/app-card-home-with-search/README.md
index 6d554e0e955..15e51a8cf8f 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/app-card-home-with-search/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/app-card-home-with-search/README.md
@@ -17,9 +17,9 @@ validated: source-proven
 
 ```ts
 // surge.gts (or row-and-rail.gts, or whatever the brand demands)
-import { CardDef, Component, field, contains, linksTo } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import TextAreaField from 'https://cardstack.com/base/text-area';
+import { CardDef, Component, field, contains, linksTo } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import TextAreaField from '@cardstack/base/text-area';
 import {
   codeRef,
   realmURL,
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/attach-remote-image/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/attach-remote-image/README.md
index 0e7c76e37b0..fd6b5cebab7 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/attach-remote-image/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/attach-remote-image/README.md
@@ -24,10 +24,10 @@ Two fields, one logical concept, template-side resolution.
 ### Schema (single image)
 
 ```gts
-import { CardDef, Component, contains, field, linksTo } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import UrlField from 'https://cardstack.com/base/url';
-import ImageDef from 'https://cardstack.com/base/image';
+import { CardDef, Component, contains, field, linksTo } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import UrlField from '@cardstack/base/url';
+import ImageDef from '@cardstack/base/image';
 
 export class Property extends CardDef {
   static displayName = 'Property';
@@ -120,7 +120,7 @@ The relationship link points at a real ImageDef instance in the realm — never
 ## Gotchas
 
 - **NEVER cross-mix.** Don't put an external URL into `relationships.heroImage.links.self`. That's the realm-bricking shape. The relationship is for in-realm card identifiers only.
-- **Use `UrlField`, not `StringField`, and not `MaybeBase64Field`.** `UrlField` (from `https://cardstack.com/base/url`) extends `StringField` with URL-shape validation in edit mode. The base `cardInfo` field uses `MaybeBase64Field` for historical reasons (it also accepts inline base64) — don't follow that lead in new code; `UrlField` is the canonical choice for an external HTTP(S) URL.
+- **Use `UrlField`, not `StringField`, and not `MaybeBase64Field`.** `UrlField` (from `@cardstack/base/url`) extends `StringField` with URL-shape validation in edit mode. The base `cardInfo` field uses `MaybeBase64Field` for historical reasons (it also accepts inline base64) — don't follow that lead in new code; `UrlField` is the canonical choice for an external HTTP(S) URL.
 - **Empty string vs null.** When clearing the URL, set the JSON value to `null` not `""` — empty strings can confuse downstream consumers expecting truthiness.
 
 ## Source
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-image-steering/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-image-steering/example.gts
index 51a5a17f815..39c26e0d6e8 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-image-steering/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-image-steering/example.gts
@@ -19,9 +19,9 @@ import {
   Component,
   contains,
   field,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import TextAreaField from 'https://cardstack.com/base/text-area';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import TextAreaField from '@cardstack/base/text-area';
 import { restartableTask } from 'ember-concurrency';
 import { tracked } from '@glimmer/tracking';
 import { action } from '@ember/object';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-linked-to-me-lookup/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-linked-to-me-lookup/README.md
index 6c078da9ff6..bffe9e47237 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-linked-to-me-lookup/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-linked-to-me-lookup/README.md
@@ -59,7 +59,7 @@ When you need the list to refresh as the realm changes mid-session, or when the
 **The only working call signature** is the context-injected one:
 
 ```ts
-import { Component } from 'https://cardstack.com/base/card-api';
+import { Component } from '@cardstack/base/card-api';
 
 import { codeRef, realmURL } from '@cardstack/runtime-common';
 
@@ -103,7 +103,7 @@ static isolated = class extends Component<typeof MyCard> {
 **Source proven correct against:** `~/Projects/boxel/packages/catalog-realm/sprint-planner/components/base-task-planner.gts:214-235`, `~/Projects/boxel/packages/catalog-realm/calendar/calendar.gts:496`, `~/Projects/boxel/packages/catalog-realm/gaming-hub/gaming-hub.gts:121`, and ~10 other catalog cards. Every working in-component query in the catalog uses this exact signature.
 
 **Critical — what NOT to do:**
-- ❌ `import { getCards } from 'https://cardstack.com/base/card-api';` — compiles but `getCards` is undefined at runtime; it's only re-exported as a type.
+- ❌ `import { getCards } from '@cardstack/base/card-api';` — compiles but `getCards` is undefined at runtime; it's only re-exported as a type.
 - ❌ `import { getCards } from '@cardstack/runtime-common/get-cards';` — that module path doesn't exist at all.
 - ❌ `await getCards(query, { realmURL })` — wrong shape; no working free-function variant exists.
 - ❌ `model.id.split('/').slice(0, -2).join('/')` — fragile string parsing; use `model[realmURL]` (with `realmURL` imported as a Symbol from `@cardstack/runtime-common`) instead.
@@ -163,8 +163,8 @@ Mark each kit-internal link in the DataModelPlan with a ● in a "thunk" column.
 
 `cardOrThunk was undefined` is a general "this binding is undefined at thunk-deref time" error. Common causes besides cycles:
 
-- **Named-import of a default-only export.** `import { DateField } from 'https://cardstack.com/base/date'` resolves `DateField` to undefined; `contains(DateField)` then fails. Probe with `get-card-type-schema --input '{"codeRef":{"module":"https://cardstack.com/base/date","name":"DateField"}}'` — `Export "X" not found in module "Y"` means you need the default import (`import DateField from '...'`).
-- **Default-import from a module whose default is a DIFFERENT class.** `import ImageDef from 'https://cardstack.com/base/image'` actually gets `ImageCard` (the deprecated default of that module). Use `/base/image-file-def` or `import { ImageDef } from '/base/card-api'` (both work).
+- **Named-import of a default-only export.** `import { DateField } from '@cardstack/base/date'` resolves `DateField` to undefined; `contains(DateField)` then fails. Probe with `get-card-type-schema --input '{"codeRef":{"module":"@cardstack/base/date","name":"DateField"}}'` — `Export "X" not found in module "Y"` means you need the default import (`import DateField from '...'`).
+- **Default-import from a module whose default is a DIFFERENT class.** `import ImageDef from '@cardstack/base/image'` actually gets `ImageCard` (the deprecated default of that module). Use `@cardstack/base/image-file-def` or `import { ImageDef } from '@cardstack/base/card-api'` (both work).
 - **Bare `linksTo(X)` without thunk** when X is a kit-local class with any back-edge — see above.
 
 **Source:**
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-linked-to-me-lookup/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-linked-to-me-lookup/example.gts
index 871d576ea82..378af13cd2a 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-linked-to-me-lookup/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-linked-to-me-lookup/example.gts
@@ -4,8 +4,8 @@ import {
   contains,
   linksTo,
   Component,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import { codeRef, realmURL } from '@cardstack/runtime-common';
 
 // Sketch — your TeacherLog is defined in ./teacher-log:
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-run-command-cli/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-run-command-cli/README.md
index 3937ff9d391..5c11a500788 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-run-command-cli/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-run-command-cli/README.md
@@ -29,7 +29,7 @@ The first argument is the Command's module spec: realm URL, `::`, exported class
 ## Recipe shape
 
 ```ts
-import { Command } from 'https://cardstack.com/base/command';
+import { Command } from '@cardstack/base/command';
 
 export class ReindexInput extends CardDef {
   @field targetRealm = contains(StringField);
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-run-command-cli/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-run-command-cli/example.gts
index 14552753343..66362526c30 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-run-command-cli/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/automate-run-command-cli/example.gts
@@ -2,9 +2,9 @@ import {
   CardDef,
   field,
   contains,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import { Command } from 'https://cardstack.com/base/command';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import { Command } from '@cardstack/base/command';
 
 // 🧩 PATTERN: a Command shaped for shell invocation.
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/build-planning-cards-trio/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/build-planning-cards-trio/README.md
index 140ab939a35..751ca72e538 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/build-planning-cards-trio/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/build-planning-cards-trio/README.md
@@ -24,7 +24,7 @@ Each one is a real CardDef with `prefersWideFormat = true` so the plan reads at
 
 ```ts
 // architecture-plan.gts
-import { CardDef, Component } from 'https://cardstack.com/base/card-api';
+import { CardDef, Component } from '@cardstack/base/card-api';
 
 export class ArchitecturePlan extends CardDef {
   static displayName = 'Architecture Plan';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/build-site-config-with-theme/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/build-site-config-with-theme/example.gts
index e78d35b1416..4015f0e3827 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/build-site-config-with-theme/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/build-site-config-with-theme/example.gts
@@ -6,12 +6,12 @@ import {
   field,
   linksTo,
   linksToMany,
-} from 'https://cardstack.com/base/card-api';
-import BooleanField from 'https://cardstack.com/base/boolean';
-import NumberField from 'https://cardstack.com/base/number';
-import StringField from 'https://cardstack.com/base/string';
-import UrlField from 'https://cardstack.com/base/url';
-import ThemeCard from 'https://cardstack.com/base/theme';
+} from '@cardstack/base/card-api';
+import BooleanField from '@cardstack/base/boolean';
+import NumberField from '@cardstack/base/number';
+import StringField from '@cardstack/base/string';
+import UrlField from '@cardstack/base/url';
+import ThemeCard from '@cardstack/base/theme';
 import { eq } from '@cardstack/boxel-ui/helpers';
 
 export class PageConfig extends CardDef {
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/cardinfo-override-title/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/cardinfo-override-title/example.gts
index 1dc927b8617..a0537824e07 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/cardinfo-override-title/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/cardinfo-override-title/example.gts
@@ -1,6 +1,6 @@
-import { CardDef, field, contains } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import NumberField from 'https://cardstack.com/base/number';
+import { CardDef, field, contains } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
 
 // 🧩 PATTERN: cardTitle override — cardInfo.name first, then primary field, then default.
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-atomic-install/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-atomic-install/example.gts
index 88765517da4..a1bdec49bfa 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-atomic-install/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-atomic-install/example.gts
@@ -5,7 +5,7 @@ import {
   planInstanceInstall,
   logger,
 } from '@cardstack/runtime-common';
-import { CardDef, field, contains, StringField } from 'https://cardstack.com/base/card-api';
+import { CardDef, field, contains, StringField } from '@cardstack/base/card-api';
 import ExecuteAtomicOperationsCommand from '@cardstack/boxel-host/tools/execute-atomic-operations';
 
 // 🧩 PATTERN: Transactional realm install via atomic operations.
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-data-resource/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-data-resource/README.md
index 783e9855595..2cbc85f297e 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-data-resource/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-data-resource/README.md
@@ -13,9 +13,9 @@ validated: source-proven
 **Recipe shape:**
 
 ```ts
-import { commandData } from 'https://cardstack.com/base/resources/command-data';
+import { commandData } from '@cardstack/base/resources/command-data';
 import GetAllRealmMetasCommand from '@cardstack/boxel-host/tools/get-all-realm-metas';
-import type { GetAllRealmMetasResult } from 'https://cardstack.com/base/command';
+import type { GetAllRealmMetasResult } from '@cardstack/base/command';
 
 class MyComponent extends Component<typeof MyCard> {
   realmsResource = commandData<typeof GetAllRealmMetasResult>(
@@ -34,7 +34,7 @@ class MyComponent extends Component<typeof MyCard> {
 ```
 
 **Gotchas:**
-- The result type lives at `https://cardstack.com/base/command` — `import type { … }` not a regular import.
+- The result type lives at `@cardstack/base/command` — `import type { … }` not a regular import.
 - Cast `cardResult` to the specific result type — TypeScript can't infer past the generic.
 - The resource starts running on mount; if you want to defer, gate it with `@tracked` arguments inside an `input()` callback (see `ember-resources` docs).
 - For commands that take args, use the function form: `commandData(this, MyCommand, () => ({ arg: this.foo }))`.
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-data-resource/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-data-resource/example.gts
index 10c4fee52ea..c41e2e68f11 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-data-resource/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-data-resource/example.gts
@@ -1,10 +1,10 @@
-import { CardDef, field, contains, StringField, Component } from 'https://cardstack.com/base/card-api';
-import { commandData } from 'https://cardstack.com/base/resources/command-data';
+import { CardDef, field, contains, StringField, Component } from '@cardstack/base/card-api';
+import { commandData } from '@cardstack/base/resources/command-data';
 import GetAllRealmMetasCommand from '@cardstack/boxel-host/tools/get-all-realm-metas';
 import type {
   GetAllRealmMetasResult,
   RealmMetaField,
-} from 'https://cardstack.com/base/command';
+} from '@cardstack/base/command';
 
 // 🧩 PATTERN: commandData<T> reactive resource
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-optimistic-pipeline/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-optimistic-pipeline/example.gts
index dc70fe4fa37..f9e35f5d925 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-optimistic-pipeline/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-optimistic-pipeline/example.gts
@@ -6,10 +6,10 @@ import {
   containsMany,
   field,
   realmURL,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import NumberField from 'https://cardstack.com/base/number';
-import DatetimeField from 'https://cardstack.com/base/datetime';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
+import DatetimeField from '@cardstack/base/datetime';
 import { tracked } from '@glimmer/tracking';
 import { restartableTask } from 'ember-concurrency';
 import { on } from '@ember/modifier';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-typed-with-progress/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-typed-with-progress/example.gts
index a0a538bb21c..7cbea23ff74 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-typed-with-progress/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-typed-with-progress/example.gts
@@ -1,5 +1,5 @@
 import { Command } from '@cardstack/runtime-common/commands';
-import { CardDef, field, contains, StringField } from 'https://cardstack.com/base/card-api';
+import { CardDef, field, contains, StringField } from '@cardstack/base/card-api';
 import { tracked } from '@glimmer/tracking';
 
 // 🧩 PATTERN: Typed Command with tracked progressStep
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-with-skill-card-ref/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-with-skill-card-ref/example.gts
index b37919d25b5..e8721ba981f 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-with-skill-card-ref/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/command-with-skill-card-ref/example.gts
@@ -1,4 +1,4 @@
-import { CardDef, field, contains, StringField, Component } from 'https://cardstack.com/base/card-api';
+import { CardDef, field, contains, StringField, Component } from '@cardstack/base/card-api';
 // 🎯 NEWER PATH (2026-05+): tools/ai-assistant (was commands/use-ai-assistant).
 //    Symbol is still `UseAiAssistantCommand`.
 import UseAiAssistantCommand from '@cardstack/boxel-host/tools/ai-assistant';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/containsmany-sorted-render/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/containsmany-sorted-render/example.gts
index df84bbc825e..ef6a7b1c593 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/containsmany-sorted-render/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/containsmany-sorted-render/example.gts
@@ -6,9 +6,9 @@ import {
   contains,
   containsMany,
   Component,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import DateTimeField from 'https://cardstack.com/base/datetime';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import DateTimeField from '@cardstack/base/datetime';
 
 // 🧩 PATTERN: containsmany-sorted-render
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/format-morph-shared-component/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/format-morph-shared-component/README.md
index 67b602090a3..9da8a127ebf 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/format-morph-shared-component/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/format-morph-shared-component/README.md
@@ -29,7 +29,7 @@ import {
   type FieldsTypeFor,
   type EditCardFn,
   type Format,
-} from 'https://cardstack.com/base/card-api';
+} from '@cardstack/base/card-api';
 import { Button } from '@cardstack/boxel-ui/components';
 import { eq } from '@cardstack/boxel-ui/helpers';
 import { on } from '@ember/modifier';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-chess-js-via-cdn/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-chess-js-via-cdn/example.gts
index f74c6e81b51..7000df8adef 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-chess-js-via-cdn/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-chess-js-via-cdn/example.gts
@@ -1,5 +1,5 @@
-import { CardDef, field, contains, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+import { CardDef, field, contains, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import { modifier } from 'ember-modifier';
 import { action } from '@ember/object';
 // @ts-expect-error esm.run is a runtime import
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-filedef-generated-image/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-filedef-generated-image/example.gts
index 18dbcab32b0..44a29da113a 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-filedef-generated-image/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-filedef-generated-image/example.gts
@@ -1,4 +1,4 @@
-import { ImageDef } from 'https://cardstack.com/base/card-api';
+import { ImageDef } from '@cardstack/base/card-api';
 import WriteBinaryFileCommand from '@cardstack/boxel-host/tools/write-binary-file';
 
 // PATTERN: generated image bytes -> realm file -> ImageDef link.
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-leaflet-via-cdn/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-leaflet-via-cdn/example.gts
index c9dadb5172d..4e293888c79 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-leaflet-via-cdn/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-leaflet-via-cdn/example.gts
@@ -1,6 +1,6 @@
-import { CardDef, field, contains, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import NumberField from 'https://cardstack.com/base/number';
+import { CardDef, field, contains, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
 import { modifier } from 'ember-modifier';
 // @ts-expect-error esm.sh is a runtime import; TS can't resolve it
 import L from 'https://esm.sh/leaflet@1.9.4';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-one-shot-llm/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-one-shot-llm/example.gts
index a68627511f9..7a9eac3f3d7 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-one-shot-llm/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-one-shot-llm/example.gts
@@ -1,4 +1,4 @@
-import { CardDef, field, contains, StringField, Component } from 'https://cardstack.com/base/card-api';
+import { CardDef, field, contains, StringField, Component } from '@cardstack/base/card-api';
 import { tracked } from '@glimmer/tracking';
 import { restartableTask } from 'ember-concurrency';
 import { action } from '@ember/object';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-openrouter-image-generation/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-openrouter-image-generation/example.gts
index 89a664fa2ac..73494b37093 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-openrouter-image-generation/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-openrouter-image-generation/example.gts
@@ -5,9 +5,9 @@ import {
   contains,
   field,
   linksTo,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import NumberField from 'https://cardstack.com/base/number';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
 import SendRequestViaProxyCommand from '@cardstack/boxel-host/tools/send-request-via-proxy';
 import WriteBinaryFileCommand from '@cardstack/boxel-host/tools/write-binary-file';
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-screenshot-card-format/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-screenshot-card-format/example.gts
index 8991e7773f1..49050e56ddf 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-screenshot-card-format/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-screenshot-card-format/example.gts
@@ -4,9 +4,9 @@ import {
   contains,
   field,
   linksTo,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import enumField from 'https://cardstack.com/base/enum';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import enumField from '@cardstack/base/enum';
 import { action } from '@ember/object';
 import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-send-request-via-proxy/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-send-request-via-proxy/example.gts
index a60bad22bf2..d61f503c430 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-send-request-via-proxy/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-send-request-via-proxy/example.gts
@@ -1,6 +1,6 @@
 import { Command } from '@cardstack/runtime-common';
-import { CardDef, field, contains } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+import { CardDef, field, contains } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import SendRequestViaProxyCommand from '@cardstack/boxel-host/tools/send-request-via-proxy';
 
 // 🧩 PATTERN: Arbitrary HTTP through SendRequestViaProxyCommand.
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-three-js-via-cdn/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-three-js-via-cdn/example.gts
index 61a10a2c046..6a2a760adc5 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-three-js-via-cdn/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-three-js-via-cdn/example.gts
@@ -1,5 +1,5 @@
-import { CardDef, field, contains, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+import { CardDef, field, contains, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import { modifier } from 'ember-modifier';
 // @ts-expect-error esm.run is a runtime import; TS can't resolve it
 import * as THREE from 'https://esm.run/three@0.169.0';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-thumbnail-card-ai/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-thumbnail-card-ai/README.md
index 61e614aa9f4..970751e96a4 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-thumbnail-card-ai/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-thumbnail-card-ai/README.md
@@ -135,7 +135,7 @@ Pair with [`link-command-menu-item`](../link-command-menu-item/README.md) to mak
 ```ts
 import { getCardMenuItems, type GetCardMenuItemParams, type MenuItemOptions } from '@cardstack/runtime-common';
 import GenerateThumbnailCommand from '@cardstack/boxel-host/tools/generate-thumbnail';
-import { realmURL } from 'https://cardstack.com/base/card-api';
+import { realmURL } from '@cardstack/base/card-api';
 import WandIcon from '@cardstack/boxel-icons/wand';
 
 class MyCard extends CardDef {
@@ -167,7 +167,7 @@ class MyCard extends CardDef {
 
 - **OpenRouter sometimes returns no image.** The model can produce text-only responses if the prompt is ambiguous or unsafe. The command throws with the model's text fallback in the error message — surface that to the user (it's usually actionable feedback like "I can't generate images of real people"). Don't swallow it.
 - **`targetCardId` patches BEFORE returning.** If the patch fails (realm permission, indexing race) you still get the file written but the `cardInfo.cardThumbnail` link doesn't land. The command throws, but the orphaned file stays in the realm. Worth a "list orphaned thumbnails" cleanup pattern if this matters at scale.
-- **`cardInfo.cardThumbnail` requires the target's CardDef to use the default cardInfo passthrough.** A CardDef that overrides `cardInfo` to a non-default shape may not have a `cardThumbnail` field — the patch will fail. Check the base [`CardInfoField`](https://cardstack.com/base/card-api) if unsure.
+- **`cardInfo.cardThumbnail` requires the target's CardDef to use the default cardInfo passthrough.** A CardDef that overrides `cardInfo` to a non-default shape may not have a `cardThumbnail` field — the patch will fail. Check the base `CardInfoField` in `@cardstack/base/card-api` if unsure.
 - **MIME → extension mapping is fixed.** PNG/JPG/WebP/GIF/SVG/AVIF only. Unrecognised MIME defaults to `png`. The OpenRouter image models almost always return PNG, so this rarely matters.
 - **`sourceImageUrl` `fetch` runs in the host, not the realm proxy.** If your source image is on a CORS-locked domain, you may need to route it through `SendRequestViaProxyCommand` first and convert to a data URL, then pass the data URL.
 - **Costs add up.** Each call is an OpenRouter image-gen request. Don't wire it to a `@tracked` getter or anything that recomputes on render — only call from explicit user actions or one-shot install flows.
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-thumbnail-card-ai/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-thumbnail-card-ai/example.gts
index 1c5d4684067..956f3e69081 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-thumbnail-card-ai/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-thumbnail-card-ai/example.gts
@@ -24,9 +24,9 @@ import {
   field,
   linksTo,
   realmURL,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import TextAreaField from 'https://cardstack.com/base/text-area';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import TextAreaField from '@cardstack/base/text-area';
 import { action } from '@ember/object';
 import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-tone-js-via-cdn/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-tone-js-via-cdn/example.gts
index ade5752fb77..cc17c261ad5 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-tone-js-via-cdn/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-tone-js-via-cdn/example.gts
@@ -3,8 +3,8 @@ import {
   Component,
   field,
   contains,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-web-audio-synthesis/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-web-audio-synthesis/example.gts
index 4cc84aa173d..0f50ed03f43 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-web-audio-synthesis/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/integrate-web-audio-synthesis/example.gts
@@ -3,8 +3,8 @@ import {
   Component,
   field,
   contains,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import { on } from '@ember/modifier';
 
 // 🧩 PATTERN: synthesized sound feedback with no library.
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-3d-card-carousel/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-3d-card-carousel/example.gts
index 3e5a5953c1e..6c41132c912 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-3d-card-carousel/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-3d-card-carousel/example.gts
@@ -3,8 +3,8 @@ import {
   Component,
   field,
   contains,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import {
   codeRef,
   realmURL,
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-design-board/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-design-board/example.gts
index d2f0ab8832f..c1033573d85 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-design-board/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-design-board/example.gts
@@ -1,4 +1,4 @@
-import { CardDef, field, linksTo, contains, StringField, Component } from 'https://cardstack.com/base/card-api';
+import { CardDef, field, linksTo, contains, StringField, Component } from '@cardstack/base/card-api';
 
 // Each section is a self-contained card. Defined elsewhere — sketch:
 class HeroSection extends CardDef {
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-kanban-drag-drop/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-kanban-drag-drop/example.gts
index b2485f01bcf..f495d08ff8d 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-kanban-drag-drop/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-kanban-drag-drop/example.gts
@@ -9,11 +9,11 @@ import {
   containsMany,
   field,
   linksToMany,
-} from 'https://cardstack.com/base/card-api';
-import BooleanField from 'https://cardstack.com/base/boolean';
-import ColorField from 'https://cardstack.com/base/color';
-import NumberField from 'https://cardstack.com/base/number';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import BooleanField from '@cardstack/base/boolean';
+import ColorField from '@cardstack/base/color';
+import NumberField from '@cardstack/base/number';
+import StringField from '@cardstack/base/string';
 
 import {
   Button,
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-sectioned-record-with-nav/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-sectioned-record-with-nav/README.md
index 3ad2f524b7e..85e2fa51434 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-sectioned-record-with-nav/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-sectioned-record-with-nav/README.md
@@ -20,8 +20,8 @@ The pattern composes naturally with `organize-sensitive-stub-pair` (the left rai
 ## Recipe shape
 
 ```ts
-import { CardDef, Component, field, contains, linksTo } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+import { CardDef, Component, field, contains, linksTo } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
 import { fn } from '@ember/helper';
@@ -138,9 +138,9 @@ Each section is a `FieldDef` with its own `embedded` view. Keep them in a siblin
 
 ```ts
 // profile-sections.gts
-import { FieldDef, Component, field, contains } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import DateField from 'https://cardstack.com/base/date';
+import { FieldDef, Component, field, contains } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import DateField from '@cardstack/base/date';
 
 export class IdentitySection extends FieldDef {
   static displayName = 'Identity';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-sectioned-record-with-nav/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-sectioned-record-with-nav/example.gts
index d96da66b383..c1907cb1c1b 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-sectioned-record-with-nav/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/layout-sectioned-record-with-nav/example.gts
@@ -15,9 +15,9 @@ import {
   FieldDef,
   field,
   contains,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import DateField from 'https://cardstack.com/base/date';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import DateField from '@cardstack/base/date';
 import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
 import { fn } from '@ember/helper';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-command-menu-item/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-command-menu-item/README.md
index c3eee01161e..e8695d86eab 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-command-menu-item/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-command-menu-item/README.md
@@ -14,7 +14,7 @@ validated: source-proven
 
 ```ts
 import { getCardMenuItems } from '@cardstack/runtime-common';
-import { type GetCardMenuItemParams } from 'https://cardstack.com/base/card-menu-items';
+import { type GetCardMenuItemParams } from '@cardstack/base/card-menu-items';
 import { type MenuItemOptions } from '@cardstack/boxel-ui/helpers';
 import MyIcon from '@cardstack/boxel-icons/sparkles';
 import MyCommand from './my-command';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-command-menu-item/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-command-menu-item/example.gts
index a5a1ce51b01..6990afcefb9 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-command-menu-item/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-command-menu-item/example.gts
@@ -3,10 +3,10 @@ import {
   CardInfoField,
   field,
   contains,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import { getCardMenuItems } from '@cardstack/runtime-common';
-import { type GetCardMenuItemParams } from 'https://cardstack.com/base/card-menu-items';
+import { type GetCardMenuItemParams } from '@cardstack/base/card-menu-items';
 import { type MenuItemOptions } from '@cardstack/boxel-ui/helpers';
 import MapPinIcon from '@cardstack/boxel-icons/map-pin';
 import BuildingIcon from '@cardstack/boxel-icons/building';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-discriminated-action-resolver/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-discriminated-action-resolver/example.gts
index 436daaea8ee..24bd48de8e4 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-discriminated-action-resolver/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-discriminated-action-resolver/example.gts
@@ -1,4 +1,4 @@
-import { CardDef } from 'https://cardstack.com/base/card-api';
+import { CardDef } from '@cardstack/base/card-api';
 
 // 🧩 PATTERN: Discriminated-union action resolver
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-flip-card/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-flip-card/example.gts
index d0325eb1384..e88e830e4a4 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-flip-card/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-flip-card/example.gts
@@ -3,8 +3,8 @@ import {
   Component,
   field,
   contains,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-host-mode-paths/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-host-mode-paths/README.md
index 69ee5cc5efa..cdd040d4fe3 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-host-mode-paths/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-host-mode-paths/README.md
@@ -49,7 +49,7 @@ A **same-realm guard** at read time enforces that `instance` points to a card in
     },
     "meta": {
       "adoptsFrom": {
-        "module": "https://cardstack.com/base/realm-config",
+        "module": "@cardstack/base/realm-config",
         "name": "RealmConfig"
       }
     }
@@ -190,4 +190,4 @@ For end-to-end test coverage, see `packages/matrix/tests/host-mode.spec.ts` —
 - [`theme-first-workflow`](../theme-first-workflow/README.md) — every routed page card wants a brand-driven theme.
 - [`show-card-list-with-views`](../show-card-list-with-views/README.md) — for the index card of a `/blog` route.
 - [`integrate-screenshot-card-format`](../integrate-screenshot-card-format/README.md) — auto-generate Open Graph images for each routed page (use the rule's target card id as the screenshot subject).
-- The base CardDef: `https://cardstack.com/base/realm-config` (`RealmConfig` + `RoutingRuleField`).
+- The base CardDef: `@cardstack/base/realm-config` (`RealmConfig` + `RoutingRuleField`).
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-host-mode-paths/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-host-mode-paths/example.gts
index 9b3cc2c5dd6..9938554d6e0 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-host-mode-paths/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-host-mode-paths/example.gts
@@ -28,7 +28,7 @@
 //     },
 //     "meta": {
 //       "adoptsFrom": {
-//         "module": "https://cardstack.com/base/realm-config",
+//         "module": "@cardstack/base/realm-config",
 //         "name": "RealmConfig"
 //       }
 //     }
@@ -40,9 +40,9 @@ import {
   Component,
   contains,
   field,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import MarkdownField from 'https://cardstack.com/base/markdown';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import MarkdownField from '@cardstack/base/markdown';
 import LayoutPageIcon from '@cardstack/boxel-icons/layout-dashboard';
 
 export class HomePage extends CardDef {
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-view-transition/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-view-transition/example.gts
index 81d39a35412..af3d161c429 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-view-transition/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/link-view-transition/example.gts
@@ -3,7 +3,7 @@ import {
   Component,
   field,
   linksToMany,
-} from 'https://cardstack.com/base/card-api';
+} from '@cardstack/base/card-api';
 import { tracked } from '@glimmer/tracking';
 import { action } from '@ember/object';
 import { on } from '@ember/modifier';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-atomic-field-factory/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-atomic-field-factory/example.gts
index 16c2dd285b4..46e593edc72 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-atomic-field-factory/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-atomic-field-factory/example.gts
@@ -1,4 +1,4 @@
-import { StringField, Component } from 'https://cardstack.com/base/card-api';
+import { StringField, Component } from '@cardstack/base/card-api';
 import { BoxelSelect } from '@cardstack/boxel-ui/components';
 import { eq } from '@cardstack/boxel-ui/helpers';
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-base-class-taxonomy/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-base-class-taxonomy/example.gts
index dc0de6dd54b..4ea4e8314aa 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-base-class-taxonomy/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-base-class-taxonomy/example.gts
@@ -1,4 +1,4 @@
-import { CardDef, field, contains, containsMany, StringField, Component } from 'https://cardstack.com/base/card-api';
+import { CardDef, field, contains, containsMany, StringField, Component } from '@cardstack/base/card-api';
 
 // 🧩 PATTERN: Empty base class as a query-by-type taxonomy.
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-recursive-fielddef/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-recursive-fielddef/example.gts
index 87760defd20..495b24d260e 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-recursive-fielddef/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-recursive-fielddef/example.gts
@@ -6,10 +6,10 @@ import {
   contains,
   containsMany,
   field,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import TextAreaField from 'https://cardstack.com/base/text-area';
-import NumberField from 'https://cardstack.com/base/number';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import TextAreaField from '@cardstack/base/text-area';
+import NumberField from '@cardstack/base/number';
 
 export class CommentThread extends FieldDef {
   static displayName = 'Comment Thread';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-resource-class-data-loader/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-resource-class-data-loader/example.gts
index 2d2b2ea7219..02e73cb99fc 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-resource-class-data-loader/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-resource-class-data-loader/example.gts
@@ -1,7 +1,7 @@
 import { Resource } from 'ember-resources';
 import { resource } from 'ember-resources';
 import { tracked } from '@glimmer/tracking';
-import { CardDef } from 'https://cardstack.com/base/card-api';
+import { CardDef } from '@cardstack/base/card-api';
 
 // 🧩 PATTERN: Resource class with BOXED constructor
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-sensitive-stub-pair/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-sensitive-stub-pair/README.md
index 0953f448ab1..96c35bcb91c 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-sensitive-stub-pair/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-sensitive-stub-pair/README.md
@@ -23,7 +23,7 @@ Two pieces make this work:
 
 ```ts
 // full-record.gts
-import { CardDef, Component, field, contains, linksTo } from 'https://cardstack.com/base/card-api';
+import { CardDef, Component, field, contains, linksTo } from '@cardstack/base/card-api';
 import { Command } from '@cardstack/runtime-common';
 import SaveCardCommand from '@cardstack/boxel-host/tools/save-card';
 
@@ -152,7 +152,7 @@ The full record's `isolated` template should open with a visible banner — "SEN
 
 - A `<full-record>.gts` card in the workspace (~1100 lines including section layout + nav + sync flow). The pattern was originally extracted from a school-LMS sensitive-record + public-stub split.
 - `SyncOperationalStubCommand` lives in the same file as the full record (single-file convention: the Command that mutates a card lives with that card).
-- Composes with: [`linksTo`](https://cardstack.com/base/card-api), `SaveCardCommand`, `Command<TInput, undefined>`.
+- Composes with: `linksTo`, `SaveCardCommand`, `Command<TInput, undefined>`.
 
 ## See also
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-sensitive-stub-pair/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-sensitive-stub-pair/example.gts
index 488f7fead91..00e1d587a0e 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-sensitive-stub-pair/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-sensitive-stub-pair/example.gts
@@ -22,9 +22,9 @@ import {
   field,
   contains,
   linksTo,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import BooleanField from 'https://cardstack.com/base/boolean';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import BooleanField from '@cardstack/base/boolean';
 import { Command } from '@cardstack/runtime-common';
 import SaveCardCommand from '@cardstack/boxel-host/tools/save-card';
 import { Button } from '@cardstack/boxel-ui/components';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-typed-activity-feed/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-typed-activity-feed/README.md
index 6b8271cbf6d..55f9b7d6fc9 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-typed-activity-feed/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-typed-activity-feed/README.md
@@ -43,11 +43,11 @@ import {
   containsMany,
   linksTo,
   linksToMany,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import BooleanField from 'https://cardstack.com/base/boolean';
-import DatetimeField from 'https://cardstack.com/base/datetime';
-import MarkdownField from 'https://cardstack.com/base/markdown';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import BooleanField from '@cardstack/base/boolean';
+import DatetimeField from '@cardstack/base/datetime';
+import MarkdownField from '@cardstack/base/markdown';
 
 import { FeedCategory, /* domain enums */ } from './enums';
 import { Subject } from './subject';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-typed-activity-feed/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-typed-activity-feed/example.gts
index dc10b3046aa..d506013bfa5 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-typed-activity-feed/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-typed-activity-feed/example.gts
@@ -15,12 +15,12 @@ import {
   field,
   contains,
   linksTo,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import BooleanField from 'https://cardstack.com/base/boolean';
-import NumberField from 'https://cardstack.com/base/number';
-import DatetimeField from 'https://cardstack.com/base/datetime';
-import MarkdownField from 'https://cardstack.com/base/markdown';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import BooleanField from '@cardstack/base/boolean';
+import NumberField from '@cardstack/base/number';
+import DatetimeField from '@cardstack/base/datetime';
+import MarkdownField from '@cardstack/base/markdown';
 
 // Minimal "subject" + "actor" stand-ins. In a real domain these are
 // the cards the feed is *about* (Subject) and *by* (Actor).
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-variant-field-dispatcher/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-variant-field-dispatcher/example.gts
index d576a8cddc0..87c06dc1282 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-variant-field-dispatcher/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/organize-variant-field-dispatcher/example.gts
@@ -1,4 +1,4 @@
-import { FieldDef, StringField, contains, field, Component } from 'https://cardstack.com/base/card-api';
+import { FieldDef, StringField, contains, field, Component } from '@cardstack/base/card-api';
 
 // 🧩 PATTERN: Variant-configuration FieldDef dispatcher
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/pick-rating/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/pick-rating/example.gts
index dc1f3a8cac6..40bb3817d38 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/pick-rating/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/pick-rating/example.gts
@@ -10,10 +10,10 @@ import {
   FieldDef,
   contains,
   field,
-} from 'https://cardstack.com/base/card-api';
-import BooleanField from 'https://cardstack.com/base/boolean';
-import NumberField from 'https://cardstack.com/base/number';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import BooleanField from '@cardstack/base/boolean';
+import NumberField from '@cardstack/base/number';
+import StringField from '@cardstack/base/string';
 import { cn, eq } from '@cardstack/boxel-ui/helpers';
 import { Star, StarHalfFill, StarFilled } from '@cardstack/boxel-ui/icons';
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/polymorphic-field-subclass/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/polymorphic-field-subclass/README.md
index afedf6ea922..1138e93859d 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/polymorphic-field-subclass/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/polymorphic-field-subclass/README.md
@@ -23,7 +23,7 @@ import {
   field,
   contains,
   StringField,
-} from 'https://cardstack.com/base/card-api';
+} from '@cardstack/base/card-api';
 import { on } from '@ember/modifier';
 
 // Base FieldDef — shared schema + default templates
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-card-list-with-views/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-card-list-with-views/example.gts
index 07afc0a98d9..4e1e2a9fb0b 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-card-list-with-views/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-card-list-with-views/example.gts
@@ -1,5 +1,5 @@
 import GlimmerComponent from '@glimmer/component';
-import { type CardContext } from 'https://cardstack.com/base/card-api';
+import { type CardContext } from '@cardstack/base/card-api';
 import {
   searchEntryWireQueryFromQuery,
   type Query,
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-count-tiles-from-query/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-count-tiles-from-query/example.gts
index 144b40e62ac..7e42148db0d 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-count-tiles-from-query/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-count-tiles-from-query/example.gts
@@ -5,8 +5,8 @@ import {
   contains,
   field,
   type CardContext,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import GlimmerComponent from '@glimmer/component';
 import { on } from '@ember/modifier';
 import { tracked } from '@glimmer/tracking';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-filedef-audio-player/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-filedef-audio-player/example.gts
index bfd7ffe620e..c114cd69608 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-filedef-audio-player/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-filedef-audio-player/example.gts
@@ -4,11 +4,11 @@ import {
   field,
   contains,
   linksTo,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import NumberField from 'https://cardstack.com/base/number';
-import FileDef from 'https://cardstack.com/base/file-api';
-import ImageDef from 'https://cardstack.com/base/image-file-def';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
+import FileDef from '@cardstack/base/file-api';
+import ImageDef from '@cardstack/base/image-file-def';
 import MusicIcon from '@cardstack/boxel-icons/music';
 
 // PATTERN: realm audio file -> linksTo(FileDef) -> native audio player.
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-list-prefer-prerendered/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-list-prefer-prerendered/example.gts
index 4e07ace79f2..55876554946 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-list-prefer-prerendered/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-list-prefer-prerendered/example.gts
@@ -1,4 +1,4 @@
-import { CardDef, Component } from 'https://cardstack.com/base/card-api';
+import { CardDef, Component } from '@cardstack/base/card-api';
 import {
   codeRef,
   realmURL,
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-pdf-annotations-filedef/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-pdf-annotations-filedef/example.gts
index 4b357dd93af..7825ff9228b 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-pdf-annotations-filedef/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-pdf-annotations-filedef/example.gts
@@ -4,10 +4,10 @@ import {
   field,
   contains,
   linksTo,
-} from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import NumberField from 'https://cardstack.com/base/number';
-import FileDef from 'https://cardstack.com/base/file-api';
+} from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
+import FileDef from '@cardstack/base/file-api';
 import { Button } from '@cardstack/boxel-ui/components';
 import { on } from '@ember/modifier';
 import { action } from '@ember/object';
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-runtime-markdown-html/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-runtime-markdown-html/README.md
index 33cb4d37b6c..25299caf290 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-runtime-markdown-html/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-runtime-markdown-html/README.md
@@ -13,8 +13,8 @@ validated: source-proven
 **Recipe shape:**
 
 ```ts
-import { Component } from 'https://cardstack.com/base/card-api';
-import MarkdownField from 'https://cardstack.com/base/markdown';
+import { Component } from '@cardstack/base/card-api';
+import MarkdownField from '@cardstack/base/markdown';
 
 class BlogPost extends CardDef {
   @field cardTitle = contains(StringField);
@@ -57,6 +57,6 @@ For finer control (custom renderers, inline rendering, embedded BFM):
 - **Mermaid + math add bundle weight.** They lazy-load on first use; first render of a card containing them takes longer.
 - **Edit format is separate.** This pattern is for `isolated`/`embedded`. For editing markdown, MarkdownField's edit template provides a textarea + live preview by default.
 
-**Source:** `boxel-catalog/blog-app/blog-post.gts` (long-form post with BFM body), `boxel-catalog/system-card/model-configuration.gts` (markdown description fields). The base implementation is in `@cardstack/boxel-ui` and `https://cardstack.com/base/markdown`.
+**Source:** `boxel-catalog/blog-app/blog-post.gts` (long-form post with BFM body), `boxel-catalog/system-card/model-configuration.gts` (markdown description fields). The base implementation is in `@cardstack/boxel-ui` and `@cardstack/base/markdown`.
 
 **See also:** `boxel-flavored-markdown` (the dialect), `boxel-markdown-format` (the inverse — emitting markdown from cards), `boxel/references/template-syntax.md` (the `<@fields.body />` delegation rule).
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-runtime-markdown-html/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-runtime-markdown-html/example.gts
index 213851b19e7..b93052f381f 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-runtime-markdown-html/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-runtime-markdown-html/example.gts
@@ -1,7 +1,7 @@
-import { CardDef, field, contains, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import MarkdownField from 'https://cardstack.com/base/markdown';
-import DateTimeField from 'https://cardstack.com/base/datetime';
+import { CardDef, field, contains, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import MarkdownField from '@cardstack/base/markdown';
+import DateTimeField from '@cardstack/base/datetime';
 
 // 🧩 PATTERN: Render BFM/markdown to HTML at runtime.
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-table-from-query/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-table-from-query/example.gts
index d998d81e75c..d9279d53773 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-table-from-query/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-table-from-query/example.gts
@@ -1,5 +1,5 @@
 import GlimmerComponent from '@glimmer/component';
-import { type CardContext } from 'https://cardstack.com/base/card-api';
+import { type CardContext } from '@cardstack/base/card-api';
 import { type Query } from '@cardstack/runtime-common';
 import { get } from '@ember/helper';
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-wiki-links/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-wiki-links/example.gts
index 64315701550..fc7ce0b6ba9 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-wiki-links/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/show-wiki-links/example.gts
@@ -7,9 +7,9 @@ import {
   contains,
   field,
   linksToMany,
-} from 'https://cardstack.com/base/card-api';
-import MarkdownField from 'https://cardstack.com/base/markdown';
-import StringField from 'https://cardstack.com/base/string';
+} from '@cardstack/base/card-api';
+import MarkdownField from '@cardstack/base/markdown';
+import StringField from '@cardstack/base/string';
 
 function slugify(name: string): string {
   return name
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/theme-first-workflow/README.md b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/theme-first-workflow/README.md
index 01889d0533f..c68934b6447 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/theme-first-workflow/README.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/theme-first-workflow/README.md
@@ -14,7 +14,7 @@ validated: source-proven
 
 When a card has `cardInfo.theme` set, the CardContainer injects those CSS variables and imports the fonts. Your templates then reference `var(--background)`, `var(--foreground)`, `var(--primary)`, `var(--font-sans)` etc. and "just work".
 
-`BrandGuide` is the richest theme shape. Use it when the theme needs logo/mark usage, brand colors, brand voice, or other identity material. When you are developing Boxel built-in features, base cards, or Boxel-branded catalog output, the style source is the built-in Boxel Brand Guide at `https://cardstack.com/base/Theme/boxel-brand-guide`.
+`BrandGuide` is the richest theme shape. Use it when the theme needs logo/mark usage, brand colors, brand voice, or other identity material. When you are developing Boxel built-in features, base cards, or Boxel-branded catalog output, the style source is the built-in Boxel Brand Guide at `@cardstack/base/Theme/boxel-brand-guide`.
 
 If you skip this step and build the card with hard-coded colors, you've wasted that effort — you'll be ripping them out when the user picks a theme.
 
@@ -27,10 +27,10 @@ Three options, in order of preference:
 1. **Reuse an existing Theme.** Most realms already have a couple. Browse `<realm>/Theme/*.json` or search with `npx boxel search` filtered on the Theme class. Pick by `styleName` / `visualDNA` fields.
 2. **Copy and edit.** Take an existing Theme, `copy-card` it, modify the `cssVariables` and `cssImports`. Catalog Themes have a "Copy and Edit" menu item built in.
 3. **Author a new Theme.** Choose the narrowest base that preserves the design intent:
-   - `https://cardstack.com/base/brand-guide` for a full brand system with logo/mark usage, functional palette, color palette, typography, voice, and detailed style guidance.
-   - `https://cardstack.com/base/detailed-style-reference` for a full style system without logo/mark material.
-   - `https://cardstack.com/base/style-reference` for a compact visual DNA reference with inspirations and wallpapers.
-   - `https://cardstack.com/base/structured-theme` for a token-only theme.
+   - `@cardstack/base/brand-guide` for a full brand system with logo/mark usage, functional palette, color palette, typography, voice, and detailed style guidance.
+   - `@cardstack/base/detailed-style-reference` for a full style system without logo/mark material.
+   - `@cardstack/base/style-reference` for a compact visual DNA reference with inspirations and wallpapers.
+   - `@cardstack/base/structured-theme` for a token-only theme.
 
 ### Step 1 — Link the theme on every instance
 
@@ -130,7 +130,7 @@ After writing the card and a sample instance, preview it in the live app to conf
 - **Without a resolved `cardTheme`, CSS variables fall back to Boxel defaults** (the `--boxel-*` chain). Your card won't crash, but it won't look distinctive.
 - **Do not flatten rich themes unnecessarily.** Minimal Themes can store raw `cssVariables`, but `StructuredTheme`, `StyleReference`, `DetailedStyleReference`, and `BrandGuide` carry structured fields that compute `cssVariables`. Preserve those fields when editing.
 - **Brand assets live on Brand Guide, not arbitrary strings.** Logo and mark material belongs in `markUsage`; brand colors belong in `brandColorPalette` and `functionalPalette`; templates consume the generated `--brand-*` variables and semantic theme variables.
-- **Boxel built-in feature work uses the Boxel Brand Guide.** For base cards, host-facing UI, and Boxel-branded catalog material, start from `https://cardstack.com/base/Theme/boxel-brand-guide` and its style rules.
+- **Boxel built-in feature work uses the Boxel Brand Guide.** For base cards, host-facing UI, and Boxel-branded catalog material, start from `@cardstack/base/Theme/boxel-brand-guide` and its style rules.
 
 **Source:** `boxel-catalog/blog-app/Theme/{modern-magazine,warm-editorial,neon-brutalist}.json` (production Themes), `packages/base/theme.gts`, `packages/base/structured-theme.gts`, `packages/base/style-reference.gts`, `packages/base/detailed-style-reference.gts`, `packages/base/brand-guide.gts`, `packages/base/brand-logo.gts`, `packages/base/brand-functional-palette.gts`, `packages/base/structured-theme-variables.gts`, and `packages/base/Theme/boxel-brand-guide.json`.
 
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/theme-first-workflow/example.gts b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/theme-first-workflow/example.gts
index 2a9c6d88071..71cfad11c62 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/theme-first-workflow/example.gts
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/patterns/theme-first-workflow/example.gts
@@ -1,6 +1,6 @@
-import { CardDef, field, contains, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import MarkdownField from 'https://cardstack.com/base/markdown';
+import { CardDef, field, contains, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import MarkdownField from '@cardstack/base/markdown';
 
 // 🧩 PATTERN: Theme-first workflow.
 //
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/references/integration-surfaces.md b/packages/boxel-cli/plugin/skills/boxel-patterns/references/integration-surfaces.md
index 6b5d424a313..be840b346f3 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/references/integration-surfaces.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/references/integration-surfaces.md
@@ -6,9 +6,9 @@ Every place a Boxel card can reach for capability. Use this as a lookup when pla
 
 ---
 
-## 1. Base Card APIs (URL-pinned)
+## 1. Base Card APIs
 
-The Boxel base realm. Always available. Imports live at `https://cardstack.com/base/<name>`.
+The Boxel base realm. Always available. Imports live at `@cardstack/base/<name>`.
 
 | Module | Provides | Use for |
 |---|---|---|
@@ -193,7 +193,7 @@ Substantial libraries shipped inside the realm filesystem rather than via npm 
 Common kinds of realm-bundled libraries:
 
 - **UI surface frameworks** — layout primitives (Layout / Pane / Form / Grid / Cell / Run / Lift), focus-tree keyboard nav, pluggable CSS themes.
-- **Computation runtimes** — bxl-style unified runtimes that combine a jq-flavored JSON query language with Excel-compatible formula libraries (Bessel, statistical, financial, engineering, validation).
+- **Computation runtimes** — unified runtimes that combine a jq-flavored JSON query language with Excel-compatible formula libraries (Bessel, statistical, financial, engineering, validation). bxl itself is no longer one of these: the host serves it as the platform module `@cardstack/bxl` (see `libraries.md` and `bxl-authoring`), and only realms carrying an older uploaded bundle still import it by relative path.
 - **Canvas / flow editors** — XYFlow-style node-graph editors, flowcharts, canvas pan/zoom.
 
 Ask the user which of these (or other) realm-bundled libraries the workspace hosts. The extension pattern (e.g. `library-<name>`) has the import root and idiomatic usage. The realm-bundle-shim convention (how to ship a library inside a realm) also lives in extensions.
diff --git a/packages/boxel-cli/plugin/skills/boxel-patterns/references/libraries.md b/packages/boxel-cli/plugin/skills/boxel-patterns/references/libraries.md
index d670abbc90f..75414ef8c4d 100644
--- a/packages/boxel-cli/plugin/skills/boxel-patterns/references/libraries.md
+++ b/packages/boxel-cli/plugin/skills/boxel-patterns/references/libraries.md
@@ -8,7 +8,7 @@ Boxel cards (`.gts` files) can import from three portable tiers of source. Use t
 
 ## Tier 1 — Boxel base (host-provided)
 
-URL-pinned imports from the Boxel base realm. Always available, no install.
+Imports from the Boxel base realm. Always available, no install.
 
 ```ts
 // Core API — CardDef, FieldDef, field decorators, Component, contains, linksTo
@@ -16,27 +16,27 @@ import {
   CardDef, FieldDef,
   field, contains, containsMany, linksTo, linksToMany,
   Component, Box,
-} from 'https://cardstack.com/base/card-api';
+} from '@cardstack/base/card-api';
 
 // Built-in field types — each in its own module
-import StringField    from 'https://cardstack.com/base/string';
-import NumberField    from 'https://cardstack.com/base/number';
-import BooleanField   from 'https://cardstack.com/base/boolean';
-import DateField      from 'https://cardstack.com/base/date';
-import DatetimeField  from 'https://cardstack.com/base/datetime';
-import MarkdownField  from 'https://cardstack.com/base/markdown';
+import StringField    from '@cardstack/base/string';
+import NumberField    from '@cardstack/base/number';
+import BooleanField   from '@cardstack/base/boolean';
+import DateField      from '@cardstack/base/date';
+import DatetimeField  from '@cardstack/base/datetime';
+import MarkdownField  from '@cardstack/base/markdown';
 
 // Code reference field (for codeRef-typed values)
-import { CodeRefField } from 'https://cardstack.com/base/code-ref';
-import { AbsoluteCodeRefField } from 'https://cardstack.com/base/code-ref';
+import { CodeRefField } from '@cardstack/base/code-ref';
+import { AbsoluteCodeRefField } from '@cardstack/base/code-ref';
 
 // Shared state across components
-import { sharedState } from 'https://cardstack.com/base/shared-state';
+import { sharedState } from '@cardstack/base/shared-state';
 
 // Skill / SkillSet / SkillPlusMarkdown
-import { Skill, SkillReference } from 'https://cardstack.com/base/skill';
-import { SkillPlusMarkdown } from 'https://cardstack.com/base/skill-plus';
-import { SkillSet } from 'https://cardstack.com/base/skill-set';
+import { Skill, SkillReference } from '@cardstack/base/skill';
+import { SkillPlusMarkdown } from '@cardstack/base/skill-plus';
+import { SkillSet } from '@cardstack/base/skill-set';
 ```
 
 ---
@@ -134,6 +134,19 @@ import { Resource, resource, use } from 'ember-resources';
 import { modifier } from 'ember-modifier';
 ```
 
+### `@cardstack/bxl` — expression language for computed fields
+
+```ts
+import { expression, fx, jq } from '@cardstack/bxl';
+```
+
+The host serves this to card code, so the bare specifier is the import and
+nothing needs hosting in the workspace. `expression()` returns a function shaped
+for `computeVia`; `fx` and `jq` are the two source tags. Only the package root
+is card-facing. Writing the expressions themselves — tag choice, what the
+`derive` profile refuses, aggregation over linked collections, and the traps
+that yield a plausible wrong value — is `bxl-authoring`.
+
 ### Utility
 
 ```ts
@@ -168,12 +181,13 @@ Audio cards can also reach for the browser's built-in `AudioContext` directly 
 
 | I want to use… | Tier | Import |
 |---|---|---|
-| `CardDef`, `FieldDef`, `Component` | 1 | `https://cardstack.com/base/card-api` |
-| `StringField`, `NumberField`, etc. | 1 | `https://cardstack.com/base/<type>` |
+| `CardDef`, `FieldDef`, `Component` | 1 | `@cardstack/base/card-api` |
+| `StringField`, `NumberField`, etc. | 1 | `@cardstack/base/<type>` |
 | `getCards`, `Command` | 2 | `@cardstack/runtime-common` |
 | `Button`, `Pill`, helpers, icons | 2 | `@cardstack/boxel-ui/{components,helpers,icons/*}` |
 | `KanbanPlane`, `KanbanPlacement`, drag/drop board helpers | 2 | `@cardstack/boxel-ui/components` |
 | Any host command (`ai-assistant`, `switch-submode`, etc.) | 2 | `@cardstack/boxel-host/tools/<name>` |
+| `expression`, `fx`, `jq` for a `computeVia` formula | 2 | `@cardstack/bxl` |
 | `restartableTask` | 2 | `ember-concurrency` |
 | `Resource`, `resource()` | 2 | `ember-resources` |
 | `modifier()` | 2 | `ember-modifier` |
diff --git a/packages/boxel-cli/plugin/skills/boxel-skill-authoring/SKILL.md b/packages/boxel-cli/plugin/skills/boxel-skill-authoring/SKILL.md
index b1113b3e333..28d382babb4 100644
--- a/packages/boxel-cli/plugin/skills/boxel-skill-authoring/SKILL.md
+++ b/packages/boxel-cli/plugin/skills/boxel-skill-authoring/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: boxel-skill-authoring
-description: Use when creating or editing a user-authored Boxel skill — a markdown file whose `boxel.kind: skill` frontmatter makes it loadable by AI assistant rooms. Covers the SKILL.md format contract, the frontmatter schema, tool declarations (codeRef forms, requiresApproval), placement conventions, and how to verify the skill indexed correctly. Activates for "write me a skill", "add a tool to my skill", or a skill that isn't showing up in the skill chooser.
+description: 'Use when creating or editing a user-authored Boxel skill — a markdown file whose `boxel.kind: skill` frontmatter makes it loadable by AI assistant rooms. Covers the SKILL.md format contract, the frontmatter schema, tool declarations (codeRef forms, requiresApproval), placement conventions, and how to verify the skill indexed correctly. Activates for "write me a skill", "add a tool to my skill", or a skill that isn''t showing up in the skill chooser.'
 boxel:
   kind: skill
 ---
diff --git a/packages/boxel-cli/plugin/skills/boxel-theme-development/SKILL.md b/packages/boxel-cli/plugin/skills/boxel-theme-development/SKILL.md
index 5afd7c47c64..0a9b5b9af50 100644
--- a/packages/boxel-cli/plugin/skills/boxel-theme-development/SKILL.md
+++ b/packages/boxel-cli/plugin/skills/boxel-theme-development/SKILL.md
@@ -31,7 +31,7 @@ Use this for the theme artifact itself. Use `boxel-design` when the task is prim
    - `StyleReference`: visual DNA, inspirations, and wallpaper imagery matter.
    - `DetailedStyleReference`: a complete design system needs documented palette, type, layout, motion, components, voice, and quality rules.
    - `BrandGuide`: logo/mark usage, official brand colors, functional palette, typography, or brand governance matters.
-   - Boxel built-in feature work: use `https://cardstack.com/base/Theme/boxel-brand-guide` as the source of truth.
+   - Boxel built-in feature work: use `@cardstack/base/Theme/boxel-brand-guide` as the source of truth.
 
 3. **Gather source material.**
    - Existing Theme/BrandGuide JSON, if present.
diff --git a/packages/boxel-cli/plugin/skills/boxel-ui-component-discovery/SKILL.md b/packages/boxel-cli/plugin/skills/boxel-ui-component-discovery/SKILL.md
index 2b2eb68bc13..a111407cb60 100644
--- a/packages/boxel-cli/plugin/skills/boxel-ui-component-discovery/SKILL.md
+++ b/packages/boxel-cli/plugin/skills/boxel-ui-component-discovery/SKILL.md
@@ -47,7 +47,7 @@ of truth for what's available and what each component is called.
    ```sh
    boxel search --realm <catalog-realm-url> --query '{
      "filter": {
-       "on": { "module": "https://cardstack.com/base/spec", "name": "Spec" },
+       "on": { "module": "@cardstack/base/spec", "name": "Spec" },
        "eq": { "specType": "component" }
      }
    }' --json
diff --git a/packages/boxel-cli/plugin/skills/boxel-workspace-cardinal-rules/SKILL.md b/packages/boxel-cli/plugin/skills/boxel-workspace-cardinal-rules/SKILL.md
index 7367c0ba8e3..fd1db873b97 100644
--- a/packages/boxel-cli/plugin/skills/boxel-workspace-cardinal-rules/SKILL.md
+++ b/packages/boxel-cli/plugin/skills/boxel-workspace-cardinal-rules/SKILL.md
@@ -12,6 +12,11 @@ often passes indexing too, then breaks silently — corrupting the realm's index
 crashing at render, or dropping data with no error. Check every card/field you write
 against this list before finishing an issue.
 
+The numbers below are local to this file. The `boxel` skill carries a separate Cardinal
+Rules table with its own numbering, and that is the one a bare "Cardinal Rule N"
+citation in `index.md`, `CLAUDE.md`, or `AGENTS.md` refers to — several of those numbers
+are past the end of this list and do not name a rule here.
+
 ## 1. DateField vs DateTimeField value format
 
 `DateField` values are `YYYY-MM-DD` (no `T`). `DateTimeField` values are full ISO
@@ -81,26 +86,29 @@ while silently dropping some files' indexing jobs. For bulk kit/asset installs,
 in smaller batches and verify each batch's expected file count actually shows up in a
 realm search before pushing the next batch.
 
-## 8. NEVER curl / HTTP-GET a `https://cardstack.com/base/*` module URL to inspect a base card
-
-Base card module URLs (`https://cardstack.com/base/theme`, `.../base/card-api`,
-`.../base/cards/structured-theme`, etc.) are **loader-resolved module references, not
-fetchable HTTP resources.** `cardstack.com` is a marketing site — a direct GET or a
-realm op (`_mtimes`, `boxel file read`) against `cardstack.com/base/...` returns a
-generic Webflow **404 HTML page** (`data-wf-domain=... %%PUBLISH_URL_REPLACEMENT%%`),
-NOT the card. Do not keep retrying it — that page will never become the schema. To
-learn a base card's fields/shape, use the **`get_card_schema` tool** (it resolves
-through the realm server), or read an existing instance of that card already in the
-target realm. Same rule for any published `*.boxel.site` / `*.boxel.build` URL: those
-are Webflow-published sites, not realms — never point realm operations at them.
+## 8. NEVER curl / HTTP-GET a base card's module reference to inspect it
+
+Base card modules are addressed by the canonical `@cardstack/base/` prefix
+(`@cardstack/base/theme`, `@cardstack/base/card-api`,
+`@cardstack/base/cards/structured-theme`, etc.). Those are **loader-resolved module
+references, not fetchable HTTP resources** — there is no URL to GET. The older URL
+spelling `https://cardstack.com/base/...` still resolves at runtime, but do not write it
+and never fetch it: `cardstack.com` is a marketing site, so a direct GET or a realm op
+(`_mtimes`, `boxel file read`) against `cardstack.com/base/...` returns a generic
+Webflow **404 HTML page** (`data-wf-domain=... %%PUBLISH_URL_REPLACEMENT%%`), NOT the
+card. Do not keep retrying it — that page will never become the schema. To learn a base
+card's fields/shape, use the **`get_card_schema` tool** (it resolves through the realm
+server), or read an existing instance of that card already in the target realm. Same
+rule for any published `*.boxel.site` / `*.boxel.build` URL: those are Webflow-published
+sites, not realms — never point realm operations at them.
 
 Also: many base cards are **default exports**, so the schema ref is `name: "default"`,
 NOT the class name. The base **Theme** card is the default export of
-`https://cardstack.com/base/theme` (the module is `export default Theme`) — query it as
-module `https://cardstack.com/base/theme`, name `default` (querying `#Theme` fails).
+`@cardstack/base/theme` (the module is `export default Theme`) — query it as
+module `@cardstack/base/theme`, name `default` (querying `#Theme` fails).
 `StructuredTheme` is likewise the default export of `base/structured-theme`. When a
 `get_card_schema` call fails with "named export is a CardDef", retry with `name:
-"default"` before assuming the card is unreachable — do NOT fall back to curling the URL.
+"default"` before assuming the card is unreachable — do NOT fall back to curling a URL.
 
 ## 9. Never call `serializeCard(model)` from a render getter
 
@@ -112,3 +120,13 @@ IDResolver error `conflicting instance id in store` — the serialize path re-re
 the instance under a conflicting local id. When a template needs a JSON:API-shaped
 view of the card, reconstruct the shape from `@model` fields instead of calling
 `serializeCard`.
+
+## 10. `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.
diff --git a/packages/boxel-cli/plugin/skills/boxel/SKILL.md b/packages/boxel-cli/plugin/skills/boxel/SKILL.md
index 37895810bca..4d10b27a1fa 100644
--- a/packages/boxel-cli/plugin/skills/boxel/SKILL.md
+++ b/packages/boxel-cli/plugin/skills/boxel/SKILL.md
@@ -28,10 +28,11 @@ You are generating idiomatic Boxel: **Card Definitions** in `.gts` (Glimmer Type
 | 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. |
 
 > **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.
+> **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
 
@@ -44,8 +45,12 @@ Generated/uploaded media payload?                    → Write bytes with WriteB
 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.
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/base-field-catalog.md b/packages/boxel-cli/plugin/skills/boxel/references/base-field-catalog.md
index e665dac491f..83e5972ab2a 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/base-field-catalog.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/base-field-catalog.md
@@ -1,31 +1,31 @@
-# Base field catalog — what ships in `https://cardstack.com/base/*`
+# Base field catalog — what ships in `@cardstack/base/*`
 
-Every field listed here is importable from a stable URL and ready to use without code. Reach for the specific type instead of `StringField` whenever the value has a known shape — you get validation, a tailored editor, formatting, and queryability for free.
+Every field listed here is importable from a stable specifier and ready to use without code. Reach for the specific type instead of `StringField` whenever the value has a known shape — you get validation, a tailored editor, formatting, and queryability for free.
 
 ## Primitives & string variants
 
 | Field | Import | Notes |
 |---|---|---|
-| `StringField` | `'https://cardstack.com/base/string'` | The default for any text. Default import. |
-| `NumberField` | `'https://cardstack.com/base/number'` | Any numeric value. Default import. |
-| `BooleanField` | `'https://cardstack.com/base/boolean'` | Checkbox in edit mode. |
-| `BigIntegerField` | `'https://cardstack.com/base/big-integer'` | For values beyond `Number.MAX_SAFE_INTEGER`. |
-| `TextAreaField` | `'https://cardstack.com/base/text-area'` | Multi-line plain text (sub-page). For paragraphs that aren't markdown. |
-| `EmailField` | `'https://cardstack.com/base/email'` | Validates as `user@domain`. Renders as `mailto:` link. |
-| `UrlField` | `'https://cardstack.com/base/url'` | Validates URL shape. Renders as `<a>` in non-edit modes. |
-| `PhoneNumberField` | `'https://cardstack.com/base/phone-number'` | Country code + national number. Compound field. |
-| `EthereumAddressField` | `'https://cardstack.com/base/ethereum-address'` | Web3 address with checksum validation. |
-| `ColorField` | `'https://cardstack.com/base/color'` | Renders a color swatch + picker in edit mode. |
+| `StringField` | `'@cardstack/base/string'` | The default for any text. Default import. |
+| `NumberField` | `'@cardstack/base/number'` | Any numeric value. Default import. |
+| `BooleanField` | `'@cardstack/base/boolean'` | Checkbox in edit mode. |
+| `BigIntegerField` | `'@cardstack/base/big-integer'` | For values beyond `Number.MAX_SAFE_INTEGER`. |
+| `TextAreaField` | `'@cardstack/base/text-area'` | Multi-line plain text (sub-page). For paragraphs that aren't markdown. |
+| `EmailField` | `'@cardstack/base/email'` | Validates as `user@domain`. Renders as `mailto:` link. |
+| `UrlField` | `'@cardstack/base/url'` | Validates URL shape. Renders as `<a>` in non-edit modes. |
+| `PhoneNumberField` | `'@cardstack/base/phone-number'` | Country code + national number. Compound field. |
+| `EthereumAddressField` | `'@cardstack/base/ethereum-address'` | Web3 address with checksum validation. |
+| `ColorField` | `'@cardstack/base/color'` | Renders a color swatch + picker in edit mode. |
 
 ## Time
 
 | Field | Import | Notes |
 |---|---|---|
-| `DateField` | `'https://cardstack.com/base/date'` | Date only (no time). JSON value MUST be `YYYY-MM-DD`. |
-| `DateTimeField` | `'https://cardstack.com/base/datetime'` | Date + time. JSON value MUST be ISO datetime with `T` — `YYYY-MM-DDTHH:MM:SS[.sss]Z`. |
-| `TimeField` | `'https://cardstack.com/base/time'` | Time of day only. |
-| `DateRangeField` | `'https://cardstack.com/base/date-range-field'` | Start + end date as a single compound field — use this instead of two `DateField`s for trips, bookings, periods. |
-| `DateTimeStampField` | `'https://cardstack.com/base/datetime-stamp'` | Immutable "stamped at" datetime. Auto-populates on first save. |
+| `DateField` | `'@cardstack/base/date'` | Date only (no time). JSON value MUST be `YYYY-MM-DD`. |
+| `DateTimeField` | `'@cardstack/base/datetime'` | Date + time. JSON value MUST be ISO datetime with `T` — `YYYY-MM-DDTHH:MM:SS[.sss]Z`. |
+| `TimeField` | `'@cardstack/base/time'` | Time of day only. |
+| `DateRangeField` | `'@cardstack/base/date-range-field'` | Start + end date as a single compound field — use this instead of two `DateField`s for trips, bookings, periods. |
+| `DateTimeStampField` | `'@cardstack/base/datetime-stamp'` | Immutable "stamped at" datetime. Auto-populates on first save. |
 
 ### 🚨 Image fields — the URL/ImageDef pair pattern
 
@@ -34,16 +34,16 @@ Every field listed here is importable from a stable URL and ready to use without
 **The fix — pair pattern modeled on `cardInfo` (`base/card-api.gts:2892-2893`):**
 
 ```ts
-import UrlField from 'https://cardstack.com/base/url';
-import ImageDef from 'https://cardstack.com/base/image-file-def';   // ← correct module
-// OR equivalently: import { ImageDef } from 'https://cardstack.com/base/card-api';
+import UrlField from '@cardstack/base/url';
+import ImageDef from '@cardstack/base/image-file-def';   // ← correct module
+// OR equivalently: import { ImageDef } from '@cardstack/base/card-api';
 
 // On the CardDef:
 @field heroImage = linksTo(() => ImageDef);  // for uploaded card-side images
 @field heroImageURL = contains(UrlField);    // for external URLs (Unsplash, CDN, S3)
 ```
 
-> **Critical import distinction.** `ImageDef` (file-backed, extends FileDef) is defined in `base/card-api.gts` and re-exported by `base/image-file-def`. Both `import ImageDef from '.../base/image-file-def'` (default) and `import { ImageDef } from '.../base/card-api'` (named) work and reference the same class. **DO NOT** write `import ImageDef from 'https://cardstack.com/base/image'` — that module's default is `ImageCard` (deprecated, extends CardDef). The local alias makes lint happy, but at runtime you get the wrong class, and the field schema is broken.
+> **Critical import distinction.** `ImageDef` (file-backed, extends FileDef) is defined in `base/card-api.gts` and re-exported by `base/image-file-def`. Both `import ImageDef from '.../base/image-file-def'` (default) and `import { ImageDef } from '.../base/card-api'` (named) work and reference the same class. **DO NOT** write `import ImageDef from '@cardstack/base/image'` — that module's default is `ImageCard` (deprecated, extends CardDef). The local alias makes lint happy, but at runtime you get the wrong class, and the field schema is broken.
 
 > **Why `UrlField` not `StringField`** (and not `MaybeBase64Field` even though `cardInfo` uses it): `UrlField` extends `StringField`, adds URL-shape validation on the edit form, and renders as a clickable link in atom format. It's the correct shape for an external HTTP(S) URL. The base `cardInfo` uses `MaybeBase64Field` for historical reasons (it accepts inline base64 too) — **don't propagate that to new code**. For new schemas, always reach for `UrlField`.
 
@@ -141,24 +141,24 @@ The mismatch will surface in the result's `error` / `stackTrace` if it's present
 
 | Field | Import | Notes |
 |---|---|---|
-| `PercentageField` | `'https://cardstack.com/base/percentage'` | Extends `NumberField`. Renders with `%` suffix in atom/embedded. |
-| `AmountWithCurrency` | `'https://cardstack.com/base/amount-with-currency'` | Compound: number + Currency link. Use for prices, balances. |
-| `CurrencyField` *(via `currency.gts`)* | `'https://cardstack.com/base/currency'` | Standalone currency code (USD/EUR/etc) for lookup tables. |
+| `PercentageField` | `'@cardstack/base/percentage'` | Extends `NumberField`. Renders with `%` suffix in atom/embedded. |
+| `AmountWithCurrency` | `'@cardstack/base/amount-with-currency'` | Compound: number + Currency link. Use for prices, balances. |
+| `CurrencyField` *(via `currency.gts`)* | `'@cardstack/base/currency'` | Standalone currency code (USD/EUR/etc) for lookup tables. |
 
 ## Geographic & physical
 
 | Field | Import | Notes |
 |---|---|---|
-| `AddressField` | `'https://cardstack.com/base/address'` | Street/city/state/zip/country as a compound field. |
-| `CountryField` | `'https://cardstack.com/base/country'` | ISO country code with display name. |
-| `CoordinateField` | `'https://cardstack.com/base/coordinate'` | Lat/long pair. Pairs with `library-leaflet` patterns. |
+| `AddressField` | `'@cardstack/base/address'` | Street/city/state/zip/country as a compound field. |
+| `CountryField` | `'@cardstack/base/country'` | ISO country code with display name. |
+| `CoordinateField` | `'@cardstack/base/coordinate'` | Lat/long pair. Pairs with `library-leaflet` patterns. |
 
 ## Markdown & rich text
 
 | Field | Import | Notes |
 |---|---|---|
-| `MarkdownField` | `'https://cardstack.com/base/markdown'` | Plain CommonMark string. Renders to HTML in non-edit; textarea editor. |
-| `RichMarkdownField` | `'https://cardstack.com/base/rich-markdown'` | BFM-aware authoring surface with toolbar + slash menu. Use for cards where the body is the primary content (blog posts, docs). |
+| `MarkdownField` | `'@cardstack/base/markdown'` | Plain CommonMark string. Renders to HTML in non-edit; textarea editor. |
+| `RichMarkdownField` | `'@cardstack/base/rich-markdown'` | BFM-aware authoring surface with toolbar + slash menu. Use for cards where the body is the primary content (blog posts, docs). |
 
 ## File-backed (linksTo only)
 
@@ -166,44 +166,44 @@ These extend `FileDef` and must be used with `linksTo`, never `contains`. See `b
 
 | Field | Import | Notes |
 |---|---|---|
-| `FileDef` *(generic)* | `'https://cardstack.com/base/file-api'` | Generic file slot. Use a specific subtype when possible. |
-| `ImageDef` | `'https://cardstack.com/base/image'` | Generic image. Polymorphic — accepts any image subtype. |
-| `PngDef` | `'https://cardstack.com/base/png-image-def'` | PNG-specific. |
-| `JpgDef` | `'https://cardstack.com/base/jpg-image-def'` | JPG. |
-| `WebpDef` | `'https://cardstack.com/base/webp-image-def'` | WebP. |
-| `GifDef` | `'https://cardstack.com/base/gif-image-def'` | Animated GIF. |
-| `AvifDef` | `'https://cardstack.com/base/avif-image-def'` | AVIF. |
-| `SvgDef` | `'https://cardstack.com/base/svg-image-def'` | Inline SVG. |
-| `MarkdownDef` | `'https://cardstack.com/base/markdown-file-def'` | File-backed markdown (the file IS the content; rendered server-side). |
-| `CsvFileDef` | `'https://cardstack.com/base/csv-file-def'` | CSV file with parsed access. |
-| `JsonFileDef` | `'https://cardstack.com/base/json-file-def'` | JSON file. |
-| `GtsFileDef` | `'https://cardstack.com/base/gts-file-def'` | `.gts` source file (for tooling/preview cards). |
-| `TsFileDef` | `'https://cardstack.com/base/ts-file-def'` | `.ts` source file. |
-| `TextFileDef` | `'https://cardstack.com/base/text-file-def'` | Generic text file. |
+| `FileDef` *(generic)* | `'@cardstack/base/file-api'` | Generic file slot. Use a specific subtype when possible. |
+| `ImageDef` | `'@cardstack/base/image'` | Generic image. Polymorphic — accepts any image subtype. |
+| `PngDef` | `'@cardstack/base/png-image-def'` | PNG-specific. |
+| `JpgDef` | `'@cardstack/base/jpg-image-def'` | JPG. |
+| `WebpDef` | `'@cardstack/base/webp-image-def'` | WebP. |
+| `GifDef` | `'@cardstack/base/gif-image-def'` | Animated GIF. |
+| `AvifDef` | `'@cardstack/base/avif-image-def'` | AVIF. |
+| `SvgDef` | `'@cardstack/base/svg-image-def'` | Inline SVG. |
+| `MarkdownDef` | `'@cardstack/base/markdown-file-def'` | File-backed markdown (the file IS the content; rendered server-side). |
+| `CsvFileDef` | `'@cardstack/base/csv-file-def'` | CSV file with parsed access. |
+| `JsonFileDef` | `'@cardstack/base/json-file-def'` | JSON file. |
+| `GtsFileDef` | `'@cardstack/base/gts-file-def'` | `.gts` source file (for tooling/preview cards). |
+| `TsFileDef` | `'@cardstack/base/ts-file-def'` | `.ts` source file. |
+| `TextFileDef` | `'@cardstack/base/text-file-def'` | Generic text file. |
 
 ## Metadata / schema
 
 | Field | Import | Notes |
 |---|---|---|
-| `CodeRefField` | `'https://cardstack.com/base/code-ref'` | A `{ module, name }` reference to a CardDef class. Used in command inputs, type filters, query `on:` clauses. Stored as string-pair. |
-| `AbsoluteCodeRefField` | `'https://cardstack.com/base/code-ref'` (named export) | Same shape but always resolves to absolute URLs. |
-| `RealmField` | `'https://cardstack.com/base/realm'` | A realm reference for cross-realm queries / install targets. |
-| `CssValueField` | `'https://cardstack.com/base/css-value'` | A typed CSS value (length, color, keyword) — used inside Theme system. |
-| `TypographyField` | `'https://cardstack.com/base/typography'` | Font family + scale fields — used inside Theme cards. |
+| `CodeRefField` | `'@cardstack/base/code-ref'` | A `{ module, name }` reference to a CardDef class. Used in command inputs, type filters, query `on:` clauses. Stored as string-pair. |
+| `AbsoluteCodeRefField` | `'@cardstack/base/code-ref'` (named export) | Same shape but always resolves to absolute URLs. |
+| `RealmField` | `'@cardstack/base/realm'` | A realm reference for cross-realm queries / install targets. |
+| `CssValueField` | `'@cardstack/base/css-value'` | A typed CSS value (length, color, keyword) — used inside Theme system. |
+| `TypographyField` | `'@cardstack/base/typography'` | Font family + scale fields — used inside Theme cards. |
 
 ## Enum
 
 | Helper | Import | Notes |
 |---|---|---|
-| `enumField(BaseField, { options })` | `'https://cardstack.com/base/enum'` (default export) | Wraps a base field with constrained values + a `BoxelSelect` editor. See `enumerations.md`. |
+| `enumField(BaseField, { options })` | `'@cardstack/base/enum'` (default export) | Wraps a base field with constrained values + a `BoxelSelect` editor. See `enumerations.md`. |
 
 ## Special
 
 | Field | Import | Notes |
 |---|---|---|
-| `Tag` (CardDef) | `'https://cardstack.com/base/tag'` | A standalone CardDef for tags — link with `linksToMany(Tag)`. Not a FieldDef. |
-| `PositionedCardField` | `'https://cardstack.com/base/positioned-card'` | A linksTo + x/y coordinates. For canvas/board layouts. |
-| `Base64ImageField` | `'https://cardstack.com/base/base64-image'` | **Deprecated for new cards.** Embeds image bytes in the JSON. Use `linksTo(ImageDef)` instead — file is stored separately and the JSON stays small. |
+| `Tag` (CardDef) | `'@cardstack/base/tag'` | A standalone CardDef for tags — link with `linksToMany(Tag)`. Not a FieldDef. |
+| `PositionedCardField` | `'@cardstack/base/positioned-card'` | A linksTo + x/y coordinates. For canvas/board layouts. |
+| `Base64ImageField` | `'@cardstack/base/base64-image'` | **Deprecated for new cards.** Embeds image bytes in the JSON. Use `linksTo(ImageDef)` instead — file is stored separately and the JSON stays small. |
 
 ## Decision guide
 
@@ -241,4 +241,4 @@ Need to point at another realm?
 └── RealmField
 ```
 
-**Source:** `~/Projects/boxel/packages/base/*.gts` — every field with a `displayName` + `extends FieldDef` is importable from `https://cardstack.com/base/<file-stem>`.
+**Source:** `~/Projects/boxel/packages/base/*.gts` — every field with a `displayName` + `extends FieldDef` is importable from `@cardstack/base/<file-stem>`.
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/command-development.md b/packages/boxel-cli/plugin/skills/boxel/references/command-development.md
index cddd2dc75df..bd4498adbb0 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/command-development.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/command-development.md
@@ -6,8 +6,8 @@ Commands extend `Command<InputCardDef, OutputCardDef | undefined>` and execute w
 
 ```gts
 import { Command } from '@cardstack/runtime-common';
-import { CardDef, field, contains } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+import { CardDef, field, contains } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 
 class MyInput extends CardDef {
   @field targetRealm = contains(StringField);
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/common-imports.md b/packages/boxel-cli/plugin/skills/boxel/references/common-imports.md
index baa8cbf2fc9..b92a2bd13c9 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/common-imports.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/common-imports.md
@@ -2,7 +2,7 @@
 
 Use this before writing or finalizing `.gts` files. Missing imports compile late and usually cost a server render/lint repair turn, so treat import preflight as part of authoring.
 
-Research note: a May 2026 scan of active `boxel-workspaces` realm/source `.gts` files found the most common modules were `https://cardstack.com/base/card-api`, base fields, `@cardstack/boxel-ui/helpers`, `@glimmer/tracking`, `@ember/modifier`, `@cardstack/boxel-ui/components`, `@ember/helper`, `@ember/object`, `ember-modifier`, and `ember-concurrency`. The common missing-import failures are template helpers/modifiers: `{{on ...}}`, `(fn ...)`, `concat`, `get`, `array`, `hash`, and Boxel helper predicates/formatters. `perform` is not a safe template helper in strict-mode realm GTS: do not import `ember-concurrency/helpers/perform`, and do not write `(perform this.someTask)`.
+Research note: a May 2026 scan of active `boxel-workspaces` realm/source `.gts` files found the most common modules were `@cardstack/base/card-api`, base fields, `@cardstack/boxel-ui/helpers`, `@glimmer/tracking`, `@ember/modifier`, `@cardstack/boxel-ui/components`, `@ember/helper`, `@ember/object`, `ember-modifier`, and `ember-concurrency`. The common missing-import failures are template helpers/modifiers: `{{on ...}}`, `(fn ...)`, `concat`, `get`, `array`, `hash`, and Boxel helper predicates/formatters. `perform` is not a safe template helper in strict-mode realm GTS: do not import `ember-concurrency/helpers/perform`, and do not write `(perform this.someTask)`.
 
 ## Import Preflight
 
@@ -45,7 +45,7 @@ import {
   field,
   linksTo,
   linksToMany,
-} from 'https://cardstack.com/base/card-api';
+} from '@cardstack/base/card-api';
 ```
 
 For query refs, follow `query-systems.md`: import `realmURL` from `@cardstack/runtime-common` and use `codeRef(...)`; do not hand-roll URLs or use `Symbol.for('realmURL')`.
@@ -53,17 +53,17 @@ For query refs, follow `query-systems.md`: import `realmURL` from `@cardstack/ru
 Common base fields:
 
 ```gts
-import StringField from 'https://cardstack.com/base/string';
-import NumberField from 'https://cardstack.com/base/number';
-import BooleanField from 'https://cardstack.com/base/boolean';
-import DateField from 'https://cardstack.com/base/date';
-import DateTimeField from 'https://cardstack.com/base/datetime';
-import MarkdownField from 'https://cardstack.com/base/markdown';
-import TextAreaField from 'https://cardstack.com/base/text-area';
-import UrlField from 'https://cardstack.com/base/url';
-import ColorField from 'https://cardstack.com/base/color';
-import EmailField from 'https://cardstack.com/base/email';
-import PhoneNumberField from 'https://cardstack.com/base/phone-number';
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
+import BooleanField from '@cardstack/base/boolean';
+import DateField from '@cardstack/base/date';
+import DateTimeField from '@cardstack/base/datetime';
+import MarkdownField from '@cardstack/base/markdown';
+import TextAreaField from '@cardstack/base/text-area';
+import UrlField from '@cardstack/base/url';
+import ColorField from '@cardstack/base/color';
+import EmailField from '@cardstack/base/email';
+import PhoneNumberField from '@cardstack/base/phone-number';
 ```
 
 Template interaction helpers:
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/core-concept.md b/packages/boxel-cli/plugin/skills/boxel/references/core-concept.md
index b41e2518ee3..cce80756a45 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/core-concept.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/core-concept.md
@@ -37,6 +37,7 @@ Boxel is a composable card-based system where information lives in self-containe
 Needs own identity? → CardDef with linksTo
 Referenced from multiple places? → CardDef with linksTo
 Referencing a file (image, doc, etc.)? → FileDef subtype with linksTo
+A card showing many others? → linksToMany if it owns the set; a query if it shows everything of that type in the realm
 Just compound data? → FieldDef with contains
 ```
 
@@ -348,21 +349,21 @@ The instance never indexes. Lint doesn't catch it.
 ```json
 "meta": {
   "adoptsFrom": {
-    "module": "https://cardstack.com/base/brand-guide",   ← no `/default`
+    "module": "@cardstack/base/brand-guide",   ← no `/default`
     "name": "default"                                       ← the export name lives here
   }
 }
 ```
 
-The `module` field is the URL the realm-server fetches. The `name` field is the named export within that module. For `export default class Foo`, `name` is `"default"`. For `export class Foo`, `name` is `"Foo"`. Conflating them — `"module": "https://cardstack.com/base/brand-guide/default"` — turns the export name into a non-existent path segment and the realm returns a 404 for the module URL.
+The `module` field is the specifier the realm-server resolves. The `name` field is the named export within that module. For `export default class Foo`, `name` is `"default"`. For `export class Foo`, `name` is `"Foo"`. Conflating them — `"module": "@cardstack/base/brand-guide/default"` — turns the export name into a non-existent path segment and the module fails to resolve.
 
 #### Theme card structure
 
-`https://cardstack.com/base/theme` is the root Theme class. The current base realm layers richer theme cards on top:
+`@cardstack/base/theme` is the root Theme class. The current base realm layers richer theme cards on top:
 
-- `StructuredTheme` (`https://cardstack.com/base/structured-theme`) adds structured `rootVariables`, `darkModeVariables`, `typography`, and `version`, then computes `cssVariables`.
-- `StyleReference` (`https://cardstack.com/base/style-reference`) adds `styleName`, `visualDNA`, `inspirations`, and `wallpaperImages`.
-- `DetailedStyleReference` (`https://cardstack.com/base/detailed-style-reference`) adds long-form style guidance for palette, typography, composition, motion, component vocabulary, voice, technical specs, quality standards, and design mindset.
-- `BrandGuide` (`https://cardstack.com/base/brand-guide`) adds `brandColorPalette`, `functionalPalette`, `typography`, and `markUsage` for logo/mark material.
+- `StructuredTheme` (`@cardstack/base/structured-theme`) adds structured `rootVariables`, `darkModeVariables`, `typography`, and `version`, then computes `cssVariables`.
+- `StyleReference` (`@cardstack/base/style-reference`) adds `styleName`, `visualDNA`, `inspirations`, and `wallpaperImages`.
+- `DetailedStyleReference` (`@cardstack/base/detailed-style-reference`) adds long-form style guidance for palette, typography, composition, motion, component vocabulary, voice, technical specs, quality standards, and design mindset.
+- `BrandGuide` (`@cardstack/base/brand-guide`) adds `brandColorPalette`, `functionalPalette`, `typography`, and `markUsage` for logo/mark material.
 
-Both minimal raw-CSS Themes and rich structured themes can work. Prefer preserving the richest existing structure instead of flattening a `BrandGuide` or `StyleReference` down to a raw `cssVariables` string. For Boxel built-in features, use the built-in Boxel Brand Guide at `https://cardstack.com/base/Theme/boxel-brand-guide`.
+Both minimal raw-CSS Themes and rich structured themes can work. Prefer preserving the richest existing structure instead of flattening a `BrandGuide` or `StyleReference` down to a raw `cssVariables` string. For Boxel built-in features, use the built-in Boxel Brand Guide at `@cardstack/base/Theme/boxel-brand-guide`.
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/core-patterns.md b/packages/boxel-cli/plugin/skills/boxel/references/core-patterns.md
index 5f534378f3d..13ec71b0021 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/core-patterns.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/core-patterns.md
@@ -46,9 +46,9 @@ export class AddressField extends FieldDef {
 
 ### 1. Card Definition with Safe Computed cardTitle
 ```gts
-import { CardDef, field, contains, linksTo, containsMany, linksToMany, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import DateField from 'https://cardstack.com/base/date';
+import { CardDef, field, contains, linksTo, containsMany, linksToMany, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import DateField from '@cardstack/base/date';
 import FileTextIcon from '@cardstack/boxel-icons/file-text';
 import { Author } from './author';
 
@@ -88,8 +88,8 @@ export class BlogPost extends CardDef {
 **CRITICAL:** Every FieldDef file must import FieldDef and MUST be exported:
 
 ```gts
-import { FieldDef, field, contains, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+import { FieldDef, field, contains, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import LocationIcon from '@cardstack/boxel-icons/map-pin';
 import { concat } from '@ember/helper';
 
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/data-management.md b/packages/boxel-cli/plugin/skills/boxel/references/data-management.md
index d2780407ccb..b296ebc8816 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/data-management.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/data-management.md
@@ -148,7 +148,7 @@ Note: Use `null`, not an empty array `[]`
 ### Path Conventions
 * **Module paths**: Relative to JSON location, no `.gts` extension
   * Local: `"../author"` or `"../../shared/address-field"`
-  * Base: `"https://cardstack.com/base/string"`
+  * Base: `"@cardstack/base/string"`
 * **Relationship paths**: Relative paths, no `.json` extension
   * `"../Author/jane-doe"` not `"../Author/jane-doe.json"`
 * **Date formats**: 
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/defensive-link-traversal.md b/packages/boxel-cli/plugin/skills/boxel/references/defensive-link-traversal.md
index 6afb77a6de9..3a824330841 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/defensive-link-traversal.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/defensive-link-traversal.md
@@ -166,7 +166,7 @@ Never feed a possibly-`undefined` slot straight into a helper that dereferences
 Plain reads collapse every non-present state to `undefined`. When you genuinely need to distinguish *still loading* from *not-found* from *errored* — e.g. to show a tailored message — use `getRelationship` from `@cardstack/runtime-common` / card-api. It is a pure read (it never re-triggers the loader) and reports each slot's true state:
 
 ```ts
-import { getRelationship } from 'https://cardstack.com/base/card-api';
+import { getRelationship } from '@cardstack/base/card-api';
 
 // singular linksTo → one RelationshipState
 let state = getRelationship(this, 'manager');
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/design-playbook.md b/packages/boxel-cli/plugin/skills/boxel/references/design-playbook.md
index 7ad8b0ba759..fb59a90096a 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/design-playbook.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/design-playbook.md
@@ -287,7 +287,7 @@ Scan your stage-1 CSS and pull every distinct decision into a named token. The T
       "cssVariables": ":root {\n  --ink: #0f172a;\n  ...\n}\n\n.dark {\n  --ink: #f1f5f9;\n  ...\n}"
     },
     "meta": {
-      "adoptsFrom": { "module": "https://cardstack.com/base/card-api", "name": "Theme" }
+      "adoptsFrom": { "module": "@cardstack/base/card-api", "name": "Theme" }
     }
   }
 }
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/enumerations.md b/packages/boxel-cli/plugin/skills/boxel/references/enumerations.md
index 68c4e714c0b..569f76d31c2 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/enumerations.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/enumerations.md
@@ -2,7 +2,7 @@
 
 **CRITICAL Import Syntax:**
 ```gts
-import enumField from 'https://cardstack.com/base/enum'; // Default import, not { enumField }
+import enumField from '@cardstack/base/enum'; // Default import, not { enumField }
 ```
 
 **Quick Start:**
@@ -41,10 +41,10 @@ Use `enumField(BaseField, { options })` to create a `FieldDef` with constrained
 
 ```gts
 // ✅ CORRECT
-import enumField from 'https://cardstack.com/base/enum';
+import enumField from '@cardstack/base/enum';
 
 // ❌ WRONG
-import { enumField } from 'https://cardstack.com/base/enum';
+import { enumField } from '@cardstack/base/enum';
 ```
 
 ## Quick Start
@@ -136,7 +136,7 @@ To make `null` selectable:
 
 **Define:**
 ```gts
-import enumField from 'https://cardstack.com/base/enum';
+import enumField from '@cardstack/base/enum';
 const Priority = enumField(StringField, { options: ['High', 'Medium', 'Low'] });
 ```
 
@@ -182,9 +182,9 @@ Both resolve to `@configuration.enum.options` for templates/formats.
 ## Complete Example
 
 ```gts
-import { CardDef, field, contains } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import enumField from 'https://cardstack.com/base/enum';
+import { CardDef, field, contains } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import enumField from '@cardstack/base/enum';
 import ArrowUpIcon from '@cardstack/boxel-icons/arrow-up';
 import ArrowDownIcon from '@cardstack/boxel-icons/arrow-down';
 
@@ -215,7 +215,7 @@ The default `<@fields.priority />` renders a `BoxelSelect` (editable). When you
 ### Read the structured option for the current value
 
 ```gts
-import enumField, { enumOptions } from 'https://cardstack.com/base/enum';
+import enumField, { enumOptions } from '@cardstack/base/enum';
 
 // In a Component getter:
 get currentPriorityLabel() {
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/external-libraries.md b/packages/boxel-cli/plugin/skills/boxel/references/external-libraries.md
index 0285ce695a2..f5651fb82ec 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/external-libraries.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/external-libraries.md
@@ -65,8 +65,8 @@ Here is an example where we are:
 Do not import `perform` from `ember-concurrency/helpers/perform`; that subpath is not fetchable in realms. Also do not use `(perform this.taskName)` directly in strict-mode templates. Define a synchronous local handler that calls `.perform()`, then bind that handler with `{{on}}`.
 
 ```
-import { CardDef, field, contains, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
+import { CardDef, field, contains, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
 import { tracked } from '@glimmer/tracking';
 import { restartableTask, timeout } from 'ember-concurrency';
 import { Button } from '@cardstack/boxel-ui/components';
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/formatters.md b/packages/boxel-cli/plugin/skills/boxel/references/formatters.md
index 3721b5559c4..797d4ed5cec 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/formatters.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/formatters.md
@@ -51,4 +51,4 @@ import {
 {{formatFileSize @model.assetBytes binary=true precision=1}}
 ```
 
-For static `markdown` templates, use `https://cardstack.com/base/markdown-helpers` instead; those helpers return pre-escaped markdown-safe strings.
+For static `markdown` templates, use `@cardstack/base/markdown-helpers` instead; those helpers return pre-escaped markdown-safe strings.
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/imagedef.md b/packages/boxel-cli/plugin/skills/boxel/references/imagedef.md
index 9a1d1c3795c..206bfa7b8a2 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/imagedef.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/imagedef.md
@@ -4,23 +4,23 @@ The canonical reference for stored / uploaded / linked image fields in Boxel. Fo
 
 ## What ImageDef is
 
-`ImageDef extends FileDef` — defined in `https://cardstack.com/base/card-api` (line 2854 of the source). It's the file-backed image type: an `ImageDef` instance is a real realm file with content-type `image/*`, a URL, and metadata. `linksTo(ImageDef)` says "this field holds a reference to that realm file."
+`ImageDef extends FileDef` — defined in `@cardstack/base/card-api` (line 2854 of the source). It's the file-backed image type: an `ImageDef` instance is a real realm file with content-type `image/*`, a URL, and metadata. `linksTo(ImageDef)` says "this field holds a reference to that realm file."
 
-`ImageCard` is a separate, deprecated class — defined in `https://cardstack.com/base/image`. It's a URL-holding CardDef, not file-backed. **Do not use `ImageCard` for new schemas.** The two are commonly confused because they both render images.
+`ImageCard` is a separate, deprecated class — defined in `@cardstack/base/image`. It's a URL-holding CardDef, not file-backed. **Do not use `ImageCard` for new schemas.** The two are commonly confused because they both render images.
 
 ## Import — three equivalent valid forms
 
 ```ts
 // Recommended for new code — explicit about which class you want
-import ImageDef from 'https://cardstack.com/base/image-file-def';
+import ImageDef from '@cardstack/base/image-file-def';
 
 // Equivalent — named import from the source module
-import { ImageDef } from 'https://cardstack.com/base/card-api';
+import { ImageDef } from '@cardstack/base/card-api';
 ```
 
 ```ts
 // FORBIDDEN — this gets ImageCard (deprecated), not ImageDef
-import ImageDef from 'https://cardstack.com/base/image';   // ← WRONG
+import ImageDef from '@cardstack/base/image';   // ← WRONG
 ```
 
 The local alias `ImageDef` makes lint happy on the wrong form. At runtime you get ImageCard, the field schema mismatches what your template expects, and downstream loads fail. Verify the right module by probing:
@@ -28,7 +28,7 @@ The local alias `ImageDef` makes lint happy on the wrong form. At runtime you ge
 ```sh
 npx boxel run-command @cardstack/boxel-host/tools/get-card-type-schema/default \
   --realm "$REALM" \
-  --input '{"codeRef":{"module":"https://cardstack.com/base/image-file-def","name":"default"}}' \
+  --input '{"codeRef":{"module":"@cardstack/base/image-file-def","name":"default"}}' \
   --json
 # status: ready → the file-backed ImageDef exists at that URL
 ```
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/query-systems.md b/packages/boxel-cli/plugin/skills/boxel/references/query-systems.md
index 0bbef2d7f8a..b1d14364299 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/query-systems.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/query-systems.md
@@ -208,7 +208,7 @@ The newer display surface for a list of results (the `<SearchResults>` component
 - Treat a query result as a field → query-backed fields (`linksTo` / `linksToMany` with a `query`).
 
 ```gts
-import { CardDef, Component } from 'https://cardstack.com/base/card-api';
+import { CardDef, Component } from '@cardstack/base/card-api';
 import {
   searchEntryWireQueryFromQuery,
   type SearchEntryWireQuery,
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/quick-reference.md b/packages/boxel-cli/plugin/skills/boxel/references/quick-reference.md
index 1b9e5756a7c..db5dd75fd6b 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/quick-reference.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/quick-reference.md
@@ -1,8 +1,8 @@
 **Core imports:**
 ```gts
-import { CardDef, FieldDef, Component, field, contains, linksTo } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import NumberField from 'https://cardstack.com/base/number';
+import { CardDef, FieldDef, Component, field, contains, linksTo } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
 ```
 
 **UI Components:**
@@ -25,44 +25,44 @@ import { formatDateTime, formatNumber, formatCurrency } from '@cardstack/boxel-u
 
 ```gts
 // Core imports - ALWAYS needed for definitions
-import { CardDef, FieldDef, Component, field, contains, containsMany, linksTo, linksToMany } from 'https://cardstack.com/base/card-api';
+import { CardDef, FieldDef, Component, field, contains, containsMany, linksTo, linksToMany } from '@cardstack/base/card-api';
 
 // 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';
-import DateField from 'https://cardstack.com/base/date';
-import DateTimeField from 'https://cardstack.com/base/datetime';
-import MarkdownField from 'https://cardstack.com/base/markdown';
-import TextAreaField from 'https://cardstack.com/base/text-area';
-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
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
+import BooleanField from '@cardstack/base/boolean';
+import DateField from '@cardstack/base/date';
+import DateTimeField from '@cardstack/base/datetime';
+import MarkdownField from '@cardstack/base/markdown';
+import TextAreaField from '@cardstack/base/text-area';
+import BigIntegerField from '@cardstack/base/big-integer';
+import CodeRefField from '@cardstack/base/code-ref';
+import Base64ImageField from '@cardstack/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)
-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
-import JpgDef from 'https://cardstack.com/base/jpg-image-def';        // .jpg/.jpeg
-import SvgDef from 'https://cardstack.com/base/svg-image-def';        // .svg
-import GifDef from 'https://cardstack.com/base/gif-image-def';        // .gif
-import WebpDef from 'https://cardstack.com/base/webp-image-def';      // .webp
-import AvifDef from 'https://cardstack.com/base/avif-image-def';      // .avif
-import MarkdownDef from 'https://cardstack.com/base/markdown-file-def'; // .md (NOT same as MarkdownField)
-import TextFileDef from 'https://cardstack.com/base/text-file-def';   // .txt
-import TsFileDef from 'https://cardstack.com/base/ts-file-def';       // .ts
-import GtsFileDef from 'https://cardstack.com/base/gts-file-def';     // .gts
-import JsonFileDef from 'https://cardstack.com/base/json-file-def';   // .json
-import CsvFileDef from 'https://cardstack.com/base/csv-file-def';     // .csv
-import ColorField from 'https://cardstack.com/base/color';
-import EmailField from 'https://cardstack.com/base/email';
-import PercentageField from 'https://cardstack.com/base/percentage';
-import PhoneNumberField from 'https://cardstack.com/base/phone-number';
-import UrlField from 'https://cardstack.com/base/url';
-import AddressField from 'https://cardstack.com/base/address';
+import FileDef from '@cardstack/base/file-api';
+import ImageDef from '@cardstack/base/image-file-def';     // any image
+import PngDef from '@cardstack/base/png-image-def';        // .png
+import JpgDef from '@cardstack/base/jpg-image-def';        // .jpg/.jpeg
+import SvgDef from '@cardstack/base/svg-image-def';        // .svg
+import GifDef from '@cardstack/base/gif-image-def';        // .gif
+import WebpDef from '@cardstack/base/webp-image-def';      // .webp
+import AvifDef from '@cardstack/base/avif-image-def';      // .avif
+import MarkdownDef from '@cardstack/base/markdown-file-def'; // .md (NOT same as MarkdownField)
+import TextFileDef from '@cardstack/base/text-file-def';   // .txt
+import TsFileDef from '@cardstack/base/ts-file-def';       // .ts
+import GtsFileDef from '@cardstack/base/gts-file-def';     // .gts
+import JsonFileDef from '@cardstack/base/json-file-def';   // .json
+import CsvFileDef from '@cardstack/base/csv-file-def';     // .csv
+import ColorField from '@cardstack/base/color';
+import EmailField from '@cardstack/base/email';
+import PercentageField from '@cardstack/base/percentage';
+import PhoneNumberField from '@cardstack/base/phone-number';
+import UrlField from '@cardstack/base/url';
+import AddressField from '@cardstack/base/address';
 
 // ⚠️ EXTENDING BASE FIELDS: To customize a base field, import it and extend:
-// import BaseAddressField from 'https://cardstack.com/base/address';
+// import BaseAddressField from '@cardstack/base/address';
 // export class FancyAddressField extends BaseAddressField { }
 // Never import and define the same field name - it causes conflicts!
 
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/relationship-loading-state.md b/packages/boxel-cli/plugin/skills/boxel/references/relationship-loading-state.md
index 2e689f3a1d5..aacaab1e74e 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/relationship-loading-state.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/relationship-loading-state.md
@@ -3,7 +3,7 @@
 A `linksTo` / `linksToMany` field loads its linked card(s) lazily, and a **query-backed** `linksToMany` resolves by running a search. Until that load or search finishes, the field has no data to show. `getRelationshipMembershipState` lets a card author render a live progress indicator for that window — a spinner that appears while the field is in flight and clears the moment it resolves.
 
 ```ts
-import { getRelationshipMembershipState } from 'https://cardstack.com/base/card-api';
+import { getRelationshipMembershipState } from '@cardstack/base/card-api';
 ```
 
 ## The shape
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/spec-usage.md b/packages/boxel-cli/plugin/skills/boxel/references/spec-usage.md
index 99f64079a39..da5804d56ed 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/spec-usage.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/spec-usage.md
@@ -4,7 +4,7 @@
 
 For each top-level card definition, write a Catalog Spec card instance in the realm's `Spec/` folder. This makes the card discoverable in the Boxel catalog.
 
-Specs adopt from the `Spec` class exported by `https://cardstack.com/base/spec` — that module lives in the base realm, not your realm.
+Specs adopt from the `Spec` class exported by `@cardstack/base/spec` — that module lives in the base realm, not your realm.
 
 ### Required shape
 
@@ -23,7 +23,7 @@ Specs adopt from the `Spec` class exported by `https://cardstack.com/base/spec`
     },
     "meta": {
       "adoptsFrom": {
-        "module": "https://cardstack.com/base/spec",
+        "module": "@cardstack/base/spec",
         "name": "Spec"
       }
     }
@@ -57,8 +57,8 @@ import { Author } from './author';
 
 **Field specs (contains/containsMany):**
 ```gts
-import StringField from 'https://cardstack.com/base/string';
-import AddressField from 'https://cardstack.com/base/address-field';
+import StringField from '@cardstack/base/string';
+import AddressField from '@cardstack/base/address-field';
 @field name = contains(StringField);
 @field addresses = containsMany(AddressField);
 ```
@@ -87,8 +87,8 @@ This document provides real-world usage examples for each spec type based on act
 #### Import
 ```typescript
 import { Author } from './author';
-import { Country } from 'https://cardstack.com/base/country';
-import { Skill } from 'https://cardstack.com/base/skill';
+import { Country } from '@cardstack/base/country';
+import { Skill } from '@cardstack/base/skill';
 ```
 
 #### Usage as a Field
@@ -121,8 +121,8 @@ export class BlogPost extends CardDef {
 
 #### Import
 ```typescript
-import StringField from 'https://cardstack.com/base/string';
-import DateField from 'https://cardstack.com/base/date';
+import StringField from '@cardstack/base/string';
+import DateField from '@cardstack/base/date';
 import { SocialMediaLink } from './social-media-link';
 ```
 
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/styling-design.md b/packages/boxel-cli/plugin/skills/boxel/references/styling-design.md
index fa7d21fee1c..5caf4b84d41 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/styling-design.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/styling-design.md
@@ -124,7 +124,7 @@ body { margin: 0; }
 {{formatNumber @model.count size="tiny"}}
 ```
 
-Canonical formatter imports live in `@cardstack/boxel-ui/helpers`, not the catalog realm. See `formatters.md` for the full list. For static `markdown` templates, use `https://cardstack.com/base/markdown-helpers` instead.
+Canonical formatter imports live in `@cardstack/boxel-ui/helpers`, not the catalog realm. See `formatters.md` for the full list. For static `markdown` templates, use `@cardstack/base/markdown-helpers` instead.
 
 ## Design Philosophy and Competitive Styling
 
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/template-syntax.md b/packages/boxel-cli/plugin/skills/boxel/references/template-syntax.md
index 7da8458f3ed..d885363ad61 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/template-syntax.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/template-syntax.md
@@ -350,9 +350,9 @@ Your templates must handle:
 ### Real-World Example: Shopping List with Featured Items
 
 ```gts
-import { CardDef, FieldDef, field, contains, containsMany, Component } from 'https://cardstack.com/base/card-api';
-import StringField from 'https://cardstack.com/base/string';
-import NumberField from 'https://cardstack.com/base/number';
+import { CardDef, FieldDef, field, contains, containsMany, Component } from '@cardstack/base/card-api';
+import StringField from '@cardstack/base/string';
+import NumberField from '@cardstack/base/number';
 import { get } from '@ember/helper';
 import { subtract } from '@cardstack/boxel-ui/helpers';
 
diff --git a/packages/boxel-cli/plugin/skills/boxel/references/theme-design-system.md b/packages/boxel-cli/plugin/skills/boxel/references/theme-design-system.md
index 77adb494e41..83344afd754 100644
--- a/packages/boxel-cli/plugin/skills/boxel/references/theme-design-system.md
+++ b/packages/boxel-cli/plugin/skills/boxel/references/theme-design-system.md
@@ -9,8 +9,8 @@
 ### 3.1 Theme Linking Rules
 Pick the source first:
 
-- **Boxel built-in feature work:** use `https://cardstack.com/base/Theme/boxel-brand-guide`. This is the Boxel style guide and brand material source.
-- **Cardstack-branded work:** use `https://cardstack.com/base/Theme/cardstack-brand-guide`.
+- **Boxel built-in feature work:** use `@cardstack/base/Theme/boxel-brand-guide`. This is the Boxel style guide and brand material source.
+- **Cardstack-branded work:** use `@cardstack/base/Theme/cardstack-brand-guide`.
 - **User/custom realm work:** choose or create a theme that fits the requested domain. Do not force Boxel styling onto an unrelated app unless the user asks for Boxel-branded output.
 - **Logo, mark, brand color, or brand material needed:** use a `BrandGuide`, not a plain `StructuredTheme`.
 
@@ -20,7 +20,7 @@ For an instance that should use the Boxel Brand Guide:
 "relationships": {
   "cardInfo.theme": {
     "links": {
-      "self": "https://cardstack.com/base/Theme/boxel-brand-guide"
+      "self": "@cardstack/base/Theme/boxel-brand-guide"
     }
   }
 }
@@ -36,19 +36,19 @@ For an instance that should use the Boxel Brand Guide:
   },
 }
 ```
-- IMPORTANT: Never set `cardInfo.theme` on ThemeCards (cards adopting from `https://cardstack.com/base/theme` or its subclasses) to avoid cycles.
+- IMPORTANT: Never set `cardInfo.theme` on ThemeCards (cards adopting from `@cardstack/base/theme` or its subclasses) to avoid cycles.
 
 #### ThemeCard Types
 
-A ThemeCard is an instance of a card definition that inherits from `https://cardstack.com/base/theme` or from one of its subclasses.
+A ThemeCard is an instance of a card definition that inherits from `@cardstack/base/theme` or from one of its subclasses.
 
-| Type | URL | Description |
+| Type | Module | Description |
 |------|-----|-------------|
-| Base Theme | `https://cardstack.com/base/theme` | Root base class |
-| Structured Theme | `https://cardstack.com/base/structured-theme` | Structured token theme. Adds `typography`, `rootVariables`, `darkModeVariables`, `version`, and computed `cssVariables`. Use for pure token systems with no brand assets. |
-| Style Reference | `https://cardstack.com/base/style-reference` | Extends `StructuredTheme`. Adds `styleName`, `inspirations`, `visualDNA`, and `wallpaperImages`. Use when the visual language matters. |
-| Detailed Style Reference | `https://cardstack.com/base/detailed-style-reference` | Extends `StyleReference`. Adds long-form guidance for context, palette, typography, geometry, material, composition, motion, components, voice, technical specs, scenarios, quality standards, and design mindset. Use for a complete design system without logo/mark assets. |
-| Brand Guide | `https://cardstack.com/base/brand-guide` | Extends `DetailedStyleReference`. Adds `brandColorPalette`, `functionalPalette`, `typography`, and `markUsage` for logo/mark material. Use whenever brand assets or brand governance matter. |
+| Base Theme | `@cardstack/base/theme` | Root base class |
+| Structured Theme | `@cardstack/base/structured-theme` | Structured token theme. Adds `typography`, `rootVariables`, `darkModeVariables`, `version`, and computed `cssVariables`. Use for pure token systems with no brand assets. |
+| Style Reference | `@cardstack/base/style-reference` | Extends `StructuredTheme`. Adds `styleName`, `inspirations`, `visualDNA`, and `wallpaperImages`. Use when the visual language matters. |
+| Detailed Style Reference | `@cardstack/base/detailed-style-reference` | Extends `StyleReference`. Adds long-form guidance for context, palette, typography, geometry, material, composition, motion, components, voice, technical specs, scenarios, quality standards, and design mindset. Use for a complete design system without logo/mark assets. |
+| Brand Guide | `@cardstack/base/brand-guide` | Extends `DetailedStyleReference`. Adds `brandColorPalette`, `functionalPalette`, `typography`, and `markUsage` for logo/mark material. Use whenever brand assets or brand governance matter. |
 
 > **When creating a Theme card:** Prefer `BrandGuide` if the output has a brand, logo, marks, or other brand material. Prefer `DetailedStyleReference` for a rich visual system without logo material. Use `StructuredTheme` only for a minimal token-only theme. At minimum, fill in `rootVariables` and `typography`. Add font URLs to `cssImports` as a string array - no `@import` needed (the system handles imports).
 
@@ -89,7 +89,7 @@ Brand Guide fallback mapping:
 - `--primary-foreground`, `--secondary-foreground`, and `--accent-foreground` are generated for contrast when absent.
 - `--font-sans` comes from root variables or the Brand Guide typography body font.
 
-The built-in Boxel Brand Guide lives at `https://cardstack.com/base/Theme/boxel-brand-guide` in shipped base content. It defines the Boxel "box element" design language: high-density UI, visible 1px frames, 8px grid discipline, color as status instead of decoration, Boxel Teal for action/selection, Cardstack Lime for rare success/highlight, and precise builder-language voice.
+The built-in Boxel Brand Guide lives at `@cardstack/base/Theme/boxel-brand-guide` in shipped base content. It defines the Boxel "box element" design language: high-density UI, visible 1px frames, 8px grid discipline, color as status instead of decoration, Boxel Teal for action/selection, Cardstack Lime for rare success/highlight, and precise builder-language voice.
 
 Current Boxel Brand Guide palette variables include `--boxel-teal`, `--boxel-cyan`, `--boxel-slate`, `--boxel-light`, `--boxel-black`, `--boxel-dove`, `--cardstack-red`, `--cardstack-lime`, `--cardstack-magenta`, `--cardstack-purple`, and `--cardstack-dark-blue`. Treat these as brand identity variables; ordinary UI should still prefer semantic roles like `--primary`, `--accent`, `--background`, and `--foreground`.
 
diff --git a/packages/boxel-cli/plugin/skills/bxl-authoring/SKILL.md b/packages/boxel-cli/plugin/skills/bxl-authoring/SKILL.md
new file mode 100644
index 00000000000..42850e48bc4
--- /dev/null
+++ b/packages/boxel-cli/plugin/skills/bxl-authoring/SKILL.md
@@ -0,0 +1,392 @@
+---
+name: bxl-authoring
+description: 'Use when writing or reviewing a BXL expression in a Boxel card — a computeVia built from expression(), the fx / jq tags, spreadsheet-formula fields, aggregations over linked or query-backed collections. Covers which tag to reach for, what the derive profile refuses outright, the silent traps (a stream where an aggregate was meant, jq interpolation in a plain string, & on a blank field, dates and "today"), and why an indexed computed can differ from the one the viewer sees. Activates on expression(, fx`…`, jq`…`, "BXL", "formula field", "computed field with Excel functions", "sum the linked cards".'
+boxel:
+  kind: skill
+---
+
+# Authoring BXL in a card
+
+BXL is the workspace's expression language: readable spreadsheet syntax and Excel
+formula libraries on top of a jq engine. In a card it drives `computeVia`.
+
+```ts
+import { expression, fx, jq } from '@cardstack/bxl';
+
+export class Claim extends CardDef {
+  @field paidAmount = contains(NumberField);
+  @field reserveAmount = contains(NumberField);
+  @field incurredAmount = contains(NumberField, {
+    computeVia: expression(fx`ROUND((PaidAmount + ReserveAmount) * 100) / 100`),
+  });
+}
+```
+
+`@cardstack/bxl` is a platform module — the host serves it to card code, so the
+bare specifier is the import. Only the package root is card-facing. `expression`
+is the factory (`bxl` and `expr` are aliases); it compiles the source once when
+the class body runs, then evaluates it against the card instance on each read.
+
+The rest of this skill is the decision layer and the trap list. For the full
+syntax surface — labels, row selectors, predicates, the Excel function matrix —
+read [bxl.boxel.site](https://bxl.boxel.site).
+
+## 1. Which tag
+
+| Source contains                             | Reach for       | Why                                                    |
+| ------------------------------------------- | --------------- | ------------------------------------------------------ |
+| `\(…)` jq interpolation                     | `` jq`…` ``     | A plain string drops the backslash — see trap 4        |
+| Excel functions (`ROUND`, `IFS`, `SUM`)     | `` fx`…` ``     | Readable-syntax compilation, explicit at the call site |
+| Bare PascalCase field labels (`PaidAmount`) | `` fx`…` ``     | The compiler resolves them to `.paidAmount`            |
+| Pure jq (`.claims \| length`)               | `` jq`…` ``     | Skips the readable-syntax compile step                 |
+| Quoted multi-word labels (`"Line Item"`)    | `fx` + `schema` | Label resolution needs the schema — see trap 3         |
+
+A plain string compiles exactly like `` fx`…` ``. Prefer a tag: it tells the next
+reader which dialect they are in, and it is the only form that survives `\(…)`.
+
+Mixing dialects inside one source is fine — `` fx`IF(.status == "Open", 1, 0)` ``
+and `` fx`if Status == "Open" then 1 else 0 end` `` both work. Case is the
+dispatch: `IF(cond, t, f)` is the Excel function, `if cond then … end` is the jq
+construct.
+
+## 2. The `derive` profile — what a computed may not do
+
+`expression()` validates against the `derive` profile **when the field is
+defined**, so a violation throws while the card module loads rather than
+producing a wrong value. The diagnostic names the rule:
+
+```text
+computeVia expression violates the derive profile:
+derive-call-banned: Profile.derive is for deterministic write/index-time
+computation and cannot use call TODAY: volatile calls are not stable write-time
+derivations.
+```
+
+Refused: volatile calls (`TODAY`, `NOW`, `RAND`, `RANDBETWEEN`, and the two
+clock-reading validator helpers `isAfter` / `isBefore`) · request, actor and
+mutation context (`@User`, `@Env`, `$new`, `$old`) · user-defined `def` helpers ·
+jq `try` / `catch` · `error` · `label` / `break` · assignment (`=`, `|=`) ·
+recursive descent (`..`) · format filters (`@csv`) · control and side-effect
+calls (`debug`, `env`, `input`, `stderr`, `halt`) · runtime metadata
+(`builtins`).
+
+Allowed and useful: `IFERROR` / `IFNA` · optional access (`.a?`) · aggregates
+(`SUM`, `AVERAGE`, `COUNT`, `NPV`) · validator helpers (`isEmail`, `isDate`) ·
+`LET` · bindings (`. as $x | …`) · explicit folds (`reduce`, `foreach`) ·
+structural ops (`keys`, `to_entries`, `group_by`, `unique`, `tojson`).
+
+`isAfter` and `isBefore` are the surprise on that list: they sit among the
+validator helpers, they look like ordinary date comparisons, and they default
+their second argument to the current time — so the profile classes them with
+`NOW`. Compare two stored dates with the operators instead
+(`` fx`StartDate < EndDate` ``), which is deterministic and needs no helper.
+
+The boundary is determinism: a derived value comes from the record snapshot, not
+from the clock, the viewer, or the request. It is computed once server-side and
+stored in the search doc, so anything ambient would bake one viewer's answer in
+for everyone.
+
+## 3. An aggregate needs a collected array, not a stream
+
+**The single most expensive trap.** jq function arguments are streams, so
+navigating into an array field and handing that straight to an aggregate calls
+the aggregate once *per element* — and the field receives an array of per-element
+results instead of one number. Nothing errors.
+
+```ts
+// WRONG — compiles to SUM(.claims[].paid); with two claims the field gets [10, 5]
+computeVia: expression(fx`SUM(Claims[].Paid)`);
+
+// RIGHT — collect first, then aggregate: 15
+computeVia: expression(fx`SUM([Claims[].Paid])`);
+
+// RIGHT — the jq spelling, with a fallback for the empty case
+computeVia: expression(jq`[.claims[] | .paidAmount] | add // 0`);
+```
+
+Same for `AVERAGE`, `COUNT`, `MAX`, `MIN`, `SUMIF`. Collect **the argument that
+iterates**, and only that one — the rule is narrower than "wrap everything", and
+wrapping the wrong thing is its own bug:
+
+- An iterating path is what needs it: `SUM([Claims[].Paid])`,
+  `SUMIF([Claims[].Paid], ">6")`.
+- A field that already holds an array is a single value. `SUM(Amounts)` over a
+  `containsMany(NumberField)` is correct as it stands.
+- A comma list is collected by the compiler, which is why the multi-argument
+  spelling has never shown the trap: `SUM(Paid, Reserve)` compiles to
+  `SUM([.paid, .reserve])`, and even `SUM(Claims[].Paid, 0)` becomes
+  `SUM([.claims[].paid, 0])`. Write the `[…]` anyway — the single-argument form
+  is what an author reaches for next.
+- **Never wrap a scalar parameter.** `ROUND([1.234], 2)` and
+  `NPV([0.1], CashFlows)` hand an array to a function that wants a number; each
+  returns null.
+
+Passing a `schema` is the other way to get this right — with field metadata, the
+compiler collects implicitly, so `SUM("Line Item"."Line Total")` compiles to
+`SUM([.lineItems[].lineTotal])`. Without a schema, quoted multi-word labels fail
+loudly (`Cannot index string with string`) and a bare PascalCase label resolves
+to a single camelCase path segment. A card gets no schema unless the expression
+passes one.
+
+Check the compiled jq when in doubt — the factory exposes it:
+
+```ts
+expression(fx`SUM([Claims[].Paid])`).bxl;
+// { source, compiledSource: 'SUM([.claims[].paid])', warnings, deps, memoize }
+```
+
+## 4. `\(…)` in a plain string is silently inert
+
+A JS string literal and an untagged template both drop the backslash before `(`,
+so the runtime never sees the interpolation and the field renders the literal
+text `(.bpSystolic)/(.bpDiastolic)`. No lint pass in a realm flags this.
+
+```ts
+// WRONG — yields "(.bpSystolic)/(.bpDiastolic)"
+computeVia: expression('"\(.bpSystolic)/\(.bpDiastolic)"');
+
+// RIGHT — the tag passes the raw source through
+computeVia: expression(jq`"\(.bpSystolic)/\(.bpDiastolic)"`);
+```
+
+Either tag preserves it — both read the raw strings, so `` fx`"\(.bpSystolic)"` ``
+interpolates too. The plain string is the one broken form.
+
+Inside `\(…)` you are in jq, and the readable-syntax pass does not reach in:
+a PascalCase label there is read as a function call, and
+`` fx`"\(PaidAmount) paid"` `` throws `'PaidAmount/0' is not defined` the first
+time the field is read. Write the path — `` fx`"\(.paidAmount) paid"` ``.
+
+## 5. Blank inputs: what propagates, what absorbs
+
+Missing and null operands are tolerated rather than fatal, which means a wrong
+answer is quiet. The model, for a card whose numeric fields are unset:
+
+| Expression                            | Result  | Reason                                      |
+| ------------------------------------- | ------- | ------------------------------------------- |
+| `` fx`Paid + Reserve` ``              | `null`  | null propagates through arithmetic          |
+| `` fx`Paid + 5` ``                    | `5`     | a null addend contributes nothing           |
+| `` fx`SUM(Paid, Reserve)` ``          | `0`     | aggregates skip blanks, Excel-style         |
+| `` fx`ROUND(Paid + Reserve)` ``       | `0`     | `ROUND` absorbs a null operand              |
+| `` fx`Premium / 0` ``                 | `null`  | division by zero yields null, not `#DIV/0!` |
+| `` jq`[.claims[] \| .paid] \| add` `` | `null`  | `add` over an empty array is null           |
+| `` jq`.name \| startswith("a")` ``    | `false` | string predicates on null are false         |
+
+Guard with `//`, the jq alternative operator: `(Paid // 0) + (Reserve // 0)`,
+`add // 0`. Because division by zero produces null rather than an error,
+`IFERROR` does **not** rescue it — guard the divisor instead.
+
+**`&` renders a blank operand as the text `null`.** `` fx`Name & " (" & Tier &
+")"` `` on a card with no tier yields `Acme (null)`. Write
+`` fx`Name & " (" & (Tier // "") & ")"` ``, or use `CONCAT` / `TEXTJOIN`, which
+drop blanks.
+
+## 6. Excel error sentinels blank the field; other failures fail the card
+
+Sentinels (`#N/A`, `#DIV/0!`, `#VALUE!`, `#REF!`, `#NUM!`) are raised as values
+inside evaluation and caught at the factory boundary, which returns `null`. That
+much is safe: `` fx`INDEX(Rows, 99)` `` leaves one blank field rather than
+failing the card.
+
+A sentinel blanks the **whole** expression, not the sub-call that raised it — it
+propagates out through every enclosing call until the boundary catches it.
+`` fx`ROUND(NA()) + 5` `` is null, not 5, even though `ROUND` absorbs a null
+operand. Catch it where you want the fallback:
+`` fx`IFERROR(VLOOKUP(Sku, Rows, 2, FALSE), "unlisted")` ``,
+`` fx`IFNA(NA(), "none")` ``. An `AVERAGE` over an empty collection raises
+`#DIV/0!` and therefore lands as null.
+
+Anything that is **not** a sentinel does fail the card. A misspelled function
+name compiles happily and throws on the first read — `` fx`SUMM([Amounts])` ``
+gives `'SUMM/1' is not defined` — and so does a structural operation applied to
+the wrong shape (`` jq`unique` `` over an object rather than an array). Those
+surface as an indexing error on the instance, not as a blank field, so a typo in
+a formula is a broken card and not a quiet null.
+
+## 7. Linked cards, query-backed inverses, and staleness
+
+Paths traverse links, including several hops: `` jq`.policy.customer.name` ``
+reads across two `linksTo` edges, and a missing hop anywhere yields null.
+
+A query-backed `linksToMany` — the inverse side, derived from a filter rather
+than stored on the card — behaves differently from a stored link, and this is
+the part worth understanding before you aggregate over one:
+
+- It resolves against the **live index at visit time**. On a realm's first index
+  pass the index is still empty, so aggregates over the inverse bake in their
+  empty-set values; the next visit of the aggregating card converges them.
+- Only stored edges drive invalidation. Writing a `Claim` reindexes that claim;
+  the `Policy` whose inverse contains it keeps the aggregate from its last visit
+  until something revisits the policy. Aggregates over an inverse are eventually
+  consistent by design.
+- The browser resolves the inverse live during render, so the number a viewer
+  sees can be the converged one while the indexed value — the one search filters
+  and sorts on — is still from the last visit.
+
+Guidance: aggregate over query-backed inverses for display and reporting; do not
+treat such a field as a promptly-correct index-time fact, and do not build a
+filter or sort that depends on it being current. When the aggregate must be
+index-accurate, put the edge on the aggregating card (a stored `linksToMany`)
+so a write to either side invalidates it. Where you accept the lag, say so in a
+comment at the field — the indexed value is server-computed and may differ from
+the one on screen, and the next reader has no other way to tell that was a
+choice.
+
+## 8. Cyclic card graphs are safe but clipped
+
+Card graphs are legitimately cyclic (a claim links to its policy, the policy's
+inverse contains the claim); jq's data model is not. Re-entering a card already
+on the traversal path yields a bounded `{ id }` reference — the same clip a
+search doc applies — so `` jq`[.claims[] | .policy.id]` `` reads one id per
+claim, and the policy's other fields read null from that direction. Structural operations
+(`unique`, `tojson`, `==`) terminate and stay field-aware, comparing cards by
+their materialized values.
+
+Two consequences for data modeling:
+
+- Read a value from the near side of a cycle, not by walking back across it. A
+  claim reaching `.policy.annualPremium` is fine; a policy reaching
+  `.claims[].policy.annualPremium` gets null.
+- A computed whose program reads the **values** of its own card — `tojson`,
+  `to_entries`, `. == .` over `.` — re-enters the field it is producing. That
+  in-flight read is blank, the spreadsheet circular-reference surface, so
+  `` jq`tojson` `` on a card yields `{"a":1,"derived":null}` rather than
+  recursing. `` jq`keys` `` is safe for the opposite reason: it reads the field
+  names, never their values, so nothing re-enters. `` jq`unique` `` over `.`
+  is not a self-reference problem at all — it throws, because `unique` wants an
+  array and a card is an object.
+
+## 9. Dates: serials are safe, "today" is not available
+
+Indexing evaluates computeds server-side; a browser evaluates them in the
+viewer's zone. Date functions are anchored so that they answer the same in
+either place: `DATE`, `EDATE`, `EOMONTH`, `WEEKDAY`, `DATEVALUE`, `YEARFRAC`,
+`DAYS`, `NETWORKDAYS` and friends give one answer across host zones. Serial
+arithmetic and explicit Y/M/D construction are the safe idioms.
+
+`TODAY` and `NOW` are not available in a computed at all — the `derive` profile
+refuses them, because an indexed value computed once from the clock is wrong for
+every later read. Nor are `isAfter` / `isBefore`, which look like plain date
+comparisons but default their second argument to the current time; compare
+stored dates with the operators (`` fx`StartDate < EndDate` ``). So:
+
+- Compute the **fact**: a due-date serial, a span between two stored dates, a
+  boolean over stored dates.
+- Render the **relative phrase** in the component, where the viewer's clock and
+  zone are the right ones. A computed that yields "3 days overdue" is a trap; one
+  that yields the due-date serial and lets the template phrase it is not.
+- If a card genuinely needs a local-time value, it belongs in the rendering
+  layer. Anything indexed is computed once, server-side, for all viewers.
+
+## 10. Memoization is per-instance and microtask-scoped
+
+`expression()` caches its result per card instance until the current microtask
+ends, which collapses the repeated synchronous reads a serialization or search
+pass makes. Glimmer flushes re-renders synchronously at the end of an action, so
+an action that **reads a formula and then writes one of that formula's inputs in
+the same burst** paints once with the cached value. It heals on the next change
+to that card. Write-only actions never see it.
+
+Pass `memoize: false` for a formula an action reads before writing its inputs:
+
+```ts
+@field statusPanel = contains(PanelField, {
+  computeVia: expression(jq`{ label: .status }`, {
+    as: PanelField,
+    memoize: false,
+  }),
+});
+```
+
+## 11. `{ as: FieldDef }` for structured output
+
+An expression yields plain JSON. When the field's type is a `FieldDef`, pass
+`as` so the value is rebuilt as an instance the serializer can identify — object
+keys map to the field def's `@field` names, nested `contains` values materialize
+as their own field-def instances, and each element of an array output gets the
+same treatment. Scalars and null pass through untouched.
+
+```ts
+export class RiskBandField extends FieldDef {
+  @field label = contains(StringField);
+  @field score = contains(NumberField);
+  @field flags = containsMany(StringField);
+}
+
+@field riskBand = contains(RiskBandField, {
+  computeVia: expression(
+    jq`{
+      label: (if .lossRatio >= 0.8 then "High" else "Low" end),
+      score: ((.lossRatio * 100) | round),
+      flags: (if .lossRatio >= 0.8 then ["review"] else [] end)
+    }`,
+    { as: RiskBandField },
+  ),
+});
+
+// containsMany — one materialized instance per element
+@field claimBands = containsMany(RiskBandField, {
+  computeVia: expression(
+    jq`[.claims[] | { label: .severityBand, score: .paidAmount }]`,
+    { as: RiskBandField },
+  ),
+});
+```
+
+Without `as`, a structured value reaches the serializer as an anonymous object
+and fails to identify.
+
+## Reviewing a card's BXL
+
+1. Every aggregate argument that iterates is collected — `SUM([Claims[].Paid])`,
+   never `SUM(Claims[].Paid)` — and no scalar parameter is.
+2. Every `\(…)` source is tagged, and every label inside `\(…)` is a jq path.
+3. Every divisor that can be blank is guarded; every `&` on a blank-able operand
+   is guarded or rewritten as `CONCAT` / `TEXTJOIN`.
+4. Date output is a serial or a span, not a rendered phrase.
+5. Aggregates over query-backed inverses are display values, not filter or sort
+   keys — and a field left to lag says so in a comment.
+6. Output shaped as an object or an array of objects for a `FieldDef`-typed field
+   has `{ as: … }`.
+7. Every function name is spelled the way the catalog spells it — a typo indexes
+   as an error, not as a blank.
+
+## Where these rules are pinned
+
+In `cardstack/boxel`, the behavior above is locked down by tests, which are the
+place to check a detail or add a case:
+
+- `packages/bxl/tests/boxel/authoring-skill-claims.ts` — this skill's own drift
+  guard: for each claim above it asserts the snippet still appears in this file
+  and still behaves as described. Editing an example here means editing that
+  suite too.
+- `packages/host/tests/helpers/cards/bxl-tracking.ts` — the worked example this
+  skill draws on: an insurance domain exercising all three tags, linked and
+  query-backed traversal, null tolerance, sentinels, and `{ as: … }`.
+- `packages/host/tests/integration/bxl-expression-test.gts` — the factory on
+  real cards, including the memoization contract.
+- `packages/host/tests/integration/bxl-platform-module-test.gts` — the platform
+  module end to end, and the query-backed first-pass/converge contract.
+- `packages/host/tests/integration/bxl-cyclic-graph-test.gts` — the `{ id }`
+  clip and structural operations across a cycle.
+- `packages/bxl/tests/boxel/` — null tolerance, tag dispatch, the `\(…)`
+  preservation rule, sentinel catching, and `as` materialization over plain
+  objects.
+- `packages/bxl/docs/` — `syntax-modes.md` (call-site modes), `profiles.md`
+  (the `derive` contract), `formulas.md` (the Excel matrix),
+  `realm-composition.md` (threading inputs into child field defs).
+
+## Adjacent skills
+
+- Query-backed `linksToMany` and inbound-reference lookups —
+  [`boxel-patterns`](../boxel-patterns/SKILL.md), pattern
+  `automate-linked-to-me-lookup`.
+- Field types, formats, and templates — [`boxel`](../boxel/SKILL.md).
+  Silent-failure traps outside BXL —
+  [`boxel-workspace-cardinal-rules`](../boxel-workspace-cardinal-rules/SKILL.md).
+- Why a card failed to index or holds broken links —
+  [`boxel-environment`](../boxel-environment/references/diagnosing-broken-links.md).
+
+The engine itself — the compiler, the jq runtime, the formula libraries, the
+mutation and authorization profiles — is documented in `packages/bxl/docs/` and
+is not this skill's subject.
diff --git a/packages/boxel-cli/plugin/skills/glossary.md b/packages/boxel-cli/plugin/skills/glossary.md
index 57bad8e1035..87164810e35 100644
--- a/packages/boxel-cli/plugin/skills/glossary.md
+++ b/packages/boxel-cli/plugin/skills/glossary.md
@@ -16,7 +16,7 @@ Entry shape: `**Term** — one-sentence definition + (optional) where it's cover
 ## 1. Core framework concepts
 
 - **Card** — A typed schema + reactive Glimmer Component + JSON instance, all colocated in a `.gts` file. The unit of construction in Boxel. → `boxel/references/core-concept.md`
-- **CardDef** — Base class for cards (full-document things — Project, Person, BlogPost). Extends from `https://cardstack.com/base/card-api`. Has `static isolated`/`embedded`/`fitted` Components.
+- **CardDef** — Base class for cards (full-document things — Project, Person, BlogPost). Extends from `@cardstack/base/card-api`. Has `static isolated`/`embedded`/`fitted` Components.
 - **FieldDef** — Base class for fields (compound or single-value building blocks reused across cards — Address, DateRange, ContactPoint). Co-located in the same file as the CardDef that owns them, or shared in their own module.
 - **Box** — The base for all values, both `CardDef` and `FieldDef` extend it; rarely referenced directly.
 - **Component** — Glimmer component associated with a CardDef format via `static isolated = class extends Component<typeof X> { <template>…</template> }`.
@@ -41,7 +41,7 @@ Entry shape: `**Term** — one-sentence definition + (optional) where it's cover
 - **linked-slot `undefined` contract** — Reading a `linksTo`/`linksToMany` is not like `contains`: a slot is `undefined` while loading and forever if broken; `linksToMany` keeps broken/unloaded slots as `undefined` holes (`arr.length` unchanged). `.filter(Boolean)` before count/render; guard every traversal. Per-slot state via `getRelationship` / `RelationshipState` (`present | not-loaded | error | not-found | not-set`). → `boxel/references/defensive-link-traversal.md`
 - **broken-link placeholder** — The DOM placeholder Boxel renders for a broken `linksTo`/`linksToMany` target — the canonical "something's wrong" signal, exposed via `data-test-broken-link-*` attributes (`error` vs `not-found`). Follow the URL to the linked instance to remediate. → `boxel-environment/references/diagnosing-broken-links.md`
 - **`computeVia: fn`** — Derive a field's value from other fields. Function runs on each access; mark with `cacheable: true` for expensive computations.
-- **`computeVia: expression(...)`** — bxl-flavored `computeVia` that runs a bxl expression with the card's fields as context. → `library-bxl`, `bxl-computevia-fields`
+- **`computeVia: expression(...)`** — bxl-flavored `computeVia` that runs a bxl expression with the card's fields as context. Validated against the `derive` profile when the field is defined, so a volatile or request-scoped expression throws as the card module loads. → `bxl-authoring`
 - **`cardInfo`** — Base CardDef field on every card. Holds `name`, `summary`, `theme` (linksTo Theme), and `cardThumbnail`. Per-instance metadata users edit via the UI.
 - **`cardTheme`** — Computed field on a CardDef that resolves which Theme to apply. Default = pass-through to `cardInfo.theme`; CardDefs override to inherit from a linked card (`this.project.cardTheme`), query for a realm default, or derive by business logic. → `theme-first-workflow`, `boxel/references/theme-design-system.md`
 - **`cardTitle`** — Computed field that surfaces the card's display label. Override to respect `cardInfo.name` first, then a primary field, then `Untitled <DisplayName>`. → `cardinfo-override-title`
@@ -101,7 +101,7 @@ The five formats every CardDef can declare via `static <format> = class extends
 - **filter predicates** — `eq`, `contains`, `range`, plus `every: [...]` / `any: [...]` for composition. Predicates require an `on:` scope.
 - **`sort`** — Array of `{ by, direction }` entries. Custom sort fields require `on: ref` inside the sort entry. Only `lastModified`, `createdAt`, `cardURL` are generalSortFields (no `on:` required).
 - **`codeRef(here, path, name)`** — Build a `ResolvedCodeRef` for use in queries. Imported from `@cardstack/runtime-common`. → `boxel/references/query-systems.md`
-- **`realmURL`** — A **Symbol** exported from `@cardstack/runtime-common` AND `https://cardstack.com/base/card-api`. **Don't write `Symbol.for('realmURL')`** — that creates a different Symbol. Read realm via `card[realmURL]?.href`.
+- **`realmURL`** — A **Symbol** exported from `@cardstack/runtime-common` AND `@cardstack/base/card-api`. **Don't write `Symbol.for('realmURL')`** — that creates a different Symbol. Read realm via `card[realmURL]?.href`.
 - **silent zero-rows traps** (memorize) — (1) `filter: { on: ref }` with no predicate. (2) Custom sort field without `on:`. (3) `Symbol.for('realmURL')` instead of the canonical Symbol import. (4) Bare `links.self` like `"Foo/bar"` instead of `"./Foo/bar"` — relationship deserialization throws and the parent card silently fails to index. (5) FileDef-typed relationships dropping the file extension (e.g. `"../guide"` instead of `"../guide.md"`) — file exists but parent card fails to type-filter. → `boxel/references/query-systems.md`, `boxel/references/card-references.md`
 - **verified query composition patterns** — Templates that have been confirmed against a live realm + indexer (not just inferred from source): `every: [{ type: ref }, { on: ref, eq: { … } }]`, `… in: { field: [values] } …`, `… range: { field: { gte: … } } …`, `… contains: { cardTitle: … } …`. Build a **validation lab card** in the realm with one `@context.searchResultsComponent` section per pattern you depend on; assert non-empty results in browser QA. → `boxel/references/query-systems.md`
 - **transient federated-search failures** — `npx boxel search` can briefly return `Realms not found` right after a new card landing while the realm-server settles. Read files back, `npx boxel realm wait-for-ready`, validate via `@context.searchResultsComponent`, then retry. → `boxel-environment/references/workflows-and-orchestration.md`
@@ -113,7 +113,7 @@ The five formats every CardDef can declare via `static <format> = class extends
 - **Style Reference** — `StructuredTheme` subclass that adds `styleName`, `inspirations`, `visualDNA`, and `wallpaperImages`. Use when the visual language needs to be documented.
 - **Detailed Style Reference** — `StyleReference` subclass with long-form design guidance: context, palette, typography, geometry, material, composition, motion, component vocabulary, voice, technical specs, application scenarios, quality standards, and design mindset.
 - **Brand Guide** — `DetailedStyleReference` subclass that adds brand assets and governance: `brandColorPalette`, `functionalPalette`, `typography`, and `markUsage`. Use when logo/mark material or official brand colors matter. → `boxel/references/theme-design-system.md`
-- **Boxel Brand Guide** — Built-in Brand Guide at `https://cardstack.com/base/Theme/boxel-brand-guide`. Source of truth for Boxel built-in feature styling, base cards, host-facing Boxel UI, and Boxel-branded catalog material.
+- **Boxel Brand Guide** — Built-in Brand Guide at `@cardstack/base/Theme/boxel-brand-guide`. Source of truth for Boxel built-in feature styling, base cards, host-facing Boxel UI, and Boxel-branded catalog material.
 - **Functional Palette** — Brand Guide field mapping brand intent to variables: `--brand-primary`, `--brand-secondary`, `--brand-accent`, `--brand-light`, and `--brand-dark`; Brand Guide maps these into semantic theme tokens when needed.
 - **Mark Usage / BrandLogo** — Brand Guide field for primary/secondary marks, greyscale marks, social profile icon, minimum heights, and clearance ratios. Emits `--brand-*-mark` variables for templates.
 - **`cardInfo.theme`** — Per-instance theme override (`linksTo(Theme)`). Wins over any computed `cardTheme`.
@@ -191,7 +191,7 @@ The dialect Boxel reads and writes. See [bfm.boxel.site](https://bfm.boxel.site)
 
 ## 12. Realm system + routing + permissions
 
-- **`realm.json`** — Card instance of `https://cardstack.com/base/realm-config` `RealmConfig` at the realm root. Holds `backgroundURL`, `iconURL`, `hostRoutingRules`, etc.
+- **`realm.json`** — Card instance of `@cardstack/base/realm-config` `RealmConfig` at the realm root. Holds `backgroundURL`, `iconURL`, `hostRoutingRules`, etc.
 - **`RealmConfig`** — Base CardDef for the realm-level config card.
 - **`RoutingRuleField`** — FieldDef inside `RealmConfig.hostRoutingRules`. Each rule = `{ path: StringField, instance: linksTo(CardDef) }`.
 - **`hostRoutingRules`** — `containsMany(RoutingRuleField)` on `RealmConfig`. Maps clean paths (`/`, `/about`, `/blog`) to cards in the same realm.
@@ -210,7 +210,7 @@ The dialect Boxel reads and writes. See [bfm.boxel.site](https://bfm.boxel.site)
 Substantial JS libraries shipped *inside* a realm filesystem rather than via npm. Realm-bundle-shim convention: a one-line `<lib>.ts` re-exporting from `./<lib>/index.ts`.
 
 - **`common-libs`** — Convention name for the realm hosting bundled libraries. Cards in other realms import via absolute URL (e.g. `<host>/common-libs/<lib>`); cards inside `common-libs` import relatively.
-- **bxl** — The workspace's unified computation runtime: a jq-flavored JSON query language + Excel-compatible formula libraries (Bessel, statistical, financial, engineering, validation). Exports `evaluateBxl`, `bxl`, `expression`, `expr`, `jq`, `fx`, `prepareBxl`, plus the formula function catalog. → `library-bxl`, `extension-libs/bxl/`, [bxl.boxel.site](https://bxl.boxel.site)
+- **bxl** — The workspace's unified computation runtime: a jq-flavored JSON query language + Excel-compatible formula libraries (Bessel, statistical, financial, engineering, validation). Exports `evaluateBxl`, `bxl`, `expression`, `expr`, `jq`, `fx`, `prepareBxl`, plus the formula function catalog. **Primary import is the platform module `@cardstack/bxl`** — the host serves it to card code, so it is not realm-bundled and needs nothing hosted in the workspace. Listed in this section only for the legacy case: a realm that carries its own uploaded bundle imports that bundle by relative path (`from '../bxl'`), which is how older realms still reach it. → `bxl-authoring`, [bxl.boxel.site](https://bxl.boxel.site)
 - **surfaces** — UI framework. Layout / Pane / Form / Grid / Cell / Run / Lift primitives + focus-tree keyboard nav + drop-in CSS themes + canvas/scene runtimes. → `library-surfaces`, `surface-form-card`, `surface-field-kit`, `surface-default-template`
 - **surfaces/grid** — Table engine. Re-exports `@tanstack/table-core` (`Row`, `RowData`, `Table`, `TableFeatures`, `createTable`, `getCoreRowModel`, `getSortedRowModel`, etc.). Reach through surfaces, not directly via esm.run.
 - **surfaces/scene** — Spatial scene runtime; ember-lume POC primitives inlined (`scene-fx-modifier`, `wheel-momentum`, `scene-runtime`, `scene-node-state`, `halo-modifier`, `camera-drag`).
@@ -254,7 +254,7 @@ Direct browser ESM imports for libraries Boxel realms don't bundle.
 - **`GenerateThumbnailCommand`** — Composes OpenRouter image-gen + `WriteBinaryFileCommand` + optional `PatchCardInstanceCommand` to patch `cardInfo.cardThumbnail`. → `integrate-thumbnail-card-ai`
 - **`ScreenshotCardCommand`** — Captures a settled PNG of any saved card at `isolated` or `embedded` format (Puppeteer-driven via prerender pool). → `integrate-screenshot-card-format`
 - **Steerable image generation** — Multi-step iterative refinement using initial prompt + steering input + first/current image lineage. → `automate-image-steering`
-- **Skill cards** — Cards typed as `Skill` from `https://cardstack.com/base/skill` that pre-load into AI rooms with their description as system context.
+- **Skill cards** — Cards typed as `Skill` from `@cardstack/base/skill` that pre-load into AI rooms with their description as system context.
 
 ## 17. Catalog system
 
@@ -345,6 +345,7 @@ Use the namespaced CLI published from the Boxel monorepo through `npx boxel`. Th
 - **`boxel-create-edit-cards`** — Thin pointer skill; content lives at `boxel-environment/references/card-tool-selection.md` (create/edit tool tables, file naming, path rules).
 - **`boxel-skill-authoring`** — SKILL.md format contract for user-authored skills: `boxel.kind: skill` frontmatter, tool declarations, verify loop.
 - **`boxel-workspace-cardinal-rules`** — Silent-failure trap checklist (DateField vs DateTimeField formats, external URLs in relationship links, `linksToMany` indexed keys, …); partially overlaps the `boxel` skill's cardinal rules under its own numbering.
+- **`bxl-authoring`** — Writing BXL in a card's `computeVia`: tag choice (plain string / `fx` / `jq`), what the `derive` profile refuses at field-definition time, collecting an aggregate's iterating argument, blank-input and error-value behavior, query-backed aggregation staleness, cyclic graphs, dates, memoization, `{ as: FieldDef }` materialization.
 - **`boxel-ui-component-discovery`** — Mandatory catalog Spec search before hand-rolling UI primitives; enumerate → one broad `boxel search` query → read `attributes.readMe` → self-audit.
 - **`ember-best-practices`** — Ember.js performance + accessibility rules, 59 `rules/*.md` files across 10 prefix-keyed categories, indexed in its SKILL.md.
 - **`catalog-listing`** — Catalog operations + submission via `SubmissionWorkflowCard`.
@@ -355,7 +356,7 @@ Use the namespaced CLI published from the Boxel monorepo through `npx boxel`. Th
 In rough priority order:
 
 - **Theme first.** Decide theme strategy before writing the card. Templates use `var(--*)` tokens, never hard-coded colors. → `theme-first-workflow`
-- **Boxel built-in feature work uses the Boxel Brand Guide.** Base cards, host-facing Boxel UI, and Boxel-branded catalog material use `https://cardstack.com/base/Theme/boxel-brand-guide` as the style source.
+- **Boxel built-in feature work uses the Boxel Brand Guide.** Base cards, host-facing Boxel UI, and Boxel-branded catalog material use `@cardstack/base/Theme/boxel-brand-guide` as the style source.
 - **`cardInfo.theme` is the per-instance override** (wins over computed `cardTheme`).
 - **Override `cardTitle` when there's a primary field.** Respect `cardInfo.name` first.
 - **Build a Home app whenever you ship 2+ related CardDefs.** `prefersWideFormat = true` + one `@context.searchResultsComponent` section per CardDef in the family. → `app-card-home-with-search`
@@ -366,13 +367,14 @@ In rough priority order:
 - **Never inline media/binary in card JSON.** Use FileDef subtypes; `WriteBinaryFileCommand` for generated bytes. → `boxel-file-def/references/no-inline-binary.md`
 - **Query traps** — `filter: { type: ref }` (not `on`); custom sort fields need `on`; `codeRef(here, …)` + `realmURL` Symbol from `@cardstack/runtime-common`. → `boxel/references/query-systems.md`
 - **🔴 DateField vs DateTimeField — silent-renders-then-crashes trap.** `contains(DateField)` value MUST be `YYYY-MM-DD`; `contains(DateTimeField)` value MUST include `T`. Mismatches pass lint + write + index, then crash at render as `RangeError: Invalid time value`. `*At` → DateTimeField; `*Date`/`*On`/`hireDate`/`dob` → DateField. → `boxel/references/base-field-catalog.md`
-- **🚨 Image URLs in relationship links BRICK the realm.** External URLs (`https://images.unsplash.com/...`) in `relationships.<field>.links.self` cause `JSON.parse` to throw on the fetched JPEG bytes; the error message's NULL byte poisons the postgres JSONB write; the entire indexing transaction rolls back. Use the `cardInfo` pair pattern: `heroImage = linksTo(ImageDef)` + `heroImageURL = contains(UrlField)` (UrlField from `https://cardstack.com/base/url`, not MaybeBase64Field, not StringField); external URLs go on the attribute side. → `boxel/references/base-field-catalog.md` "Image fields — the URL/ImageDef pair pattern"
+- **🚨 Image URLs in relationship links BRICK the realm.** External URLs (`https://images.unsplash.com/...`) in `relationships.<field>.links.self` cause `JSON.parse` to throw on the fetched JPEG bytes; the error message's NULL byte poisons the postgres JSONB write; the entire indexing transaction rolls back. Use the `cardInfo` pair pattern: `heroImage = linksTo(ImageDef)` + `heroImageURL = contains(UrlField)` (UrlField from `@cardstack/base/url`, not MaybeBase64Field, not StringField); external URLs go on the attribute side. → `boxel/references/base-field-catalog.md` "Image fields — the URL/ImageDef pair pattern"
 - **🚨 `linksToMany` JSON shape uses INDEXED KEYS, never an array.** Each item is its own top-level relationship: `"activityFeed.0": { "links": { "self": "..." } }`, not `"activityFeed": { "links": { "self": ["...", "..."] } }`. Array-in-self causes "not a card resource document".
+- **🚨 `linksTo` never in `attributes`.** Links live under `relationships`, keyed by field path (dotted keys for nested fields: `"cardInfo.theme"`); an empty link is `{ "links": { "self": null } }` or the key is omitted. A `null` attribute writes fine, then every read of the instance throws `cannot deserialize non-relationship value`.
 - **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.** 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).
+- **SEARCH/REPLACE for file creation and edits** — every text file, `.gts`, `.json`, `.md` and `README` alike. There is no file-writing tool (a tool call cannot stream, and 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/packages/boxel-cli/plugin/skills/source-code-editing/SKILL.md b/packages/boxel-cli/plugin/skills/source-code-editing/SKILL.md
index 35a5e380d04..92afafdeea0 100644
--- a/packages/boxel-cli/plugin/skills/source-code-editing/SKILL.md
+++ b/packages/boxel-cli/plugin/skills/source-code-editing/SKILL.md
@@ -29,11 +29,11 @@ Example adding an import:
 ```gts
 https://example.com/attached-file-example.gts
 ╔═══ SEARCH ════╗
-import { Component } from 'https://cardstack.com/base/card-api';
+import { Component } from '@cardstack/base/card-api';
 import { or } from '@cardstack/boxel-ui/helpers';
 ╠═══════════════╣
-import { Component } from 'https://cardstack.com/base/card-api';
-import { MarkdownField } from 'https://cardstack.com/base/markdown';
+import { Component } from '@cardstack/base/card-api';
+import { MarkdownField } from '@cardstack/base/markdown';
 import { or } from '@cardstack/boxel-ui/helpers';
 ╚═══ REPLACE ═══╝
 ```
@@ -83,8 +83,8 @@ Example creating a new file (in this case it is *CRUCIAL* to include "(new)" in
 http://users-realm/new-file-example.gts (new)
 ╔═══ SEARCH ════╗
 ╠═══════════════╣
-import { CardDef } from 'https://cardstack.com/base/card-api';
-import { Component } from 'https://cardstack.com/base/card-api';
+import { CardDef } from '@cardstack/base/card-api';
+import { Component } from '@cardstack/base/card-api';
 export class NewFileExample extends CardDef {
   static displayName = "New file example";
 }
@@ -107,7 +107,11 @@ Every *SEARCH* section must *EXACTLY MATCH* the existing file content, character
 If the file contains code or other data wrapped/escaped in json/xml/quotes or other containers, you need to propose edits to the literal contents of the file, including the container markup.
 
 *SEARCH/REPLACE* blocks will *only* replace the first match occurrence.
-Including multiple unique *SEARCH/REPLACE* blocks if needed.
+
+**Put every file a piece of work needs in one reply.** Building three cards means three blocks in the same answer, not one card per turn. They are applied together, and the correctness check then runs once over the finished result.
+
+Handing back after each file is what breaks a multi-file build. Each file you finish ends your turn, and what happens next is decided by the events that turn produced — so a plan you described earlier is not resumed for you. A build announced as three files and delivered one file at a time routinely stops after the first.
+
 Include enough lines in each SEARCH section to uniquely match each set of lines that need to change.
 
 Keep *SEARCH/REPLACE* blocks concise.
diff --git a/packages/boxel-cli/scripts/.boxel-skills-manifest.json b/packages/boxel-cli/scripts/.boxel-skills-manifest.json
index 15610a78a3f..88ef7be1d50 100644
--- a/packages/boxel-cli/scripts/.boxel-skills-manifest.json
+++ b/packages/boxel-cli/scripts/.boxel-skills-manifest.json
@@ -1,5 +1,5 @@
 {
-  "version": "v0.1.0",
+  "version": "v0.1.1",
   "skills": [
     "boxel",
     "boxel-create-edit-cards",
@@ -14,6 +14,7 @@
     "boxel-ui-component-discovery",
     "boxel-ui-guidelines",
     "boxel-workspace-cardinal-rules",
+    "bxl-authoring",
     "catalog-listing",
     "ember-best-practices",
     "glossary.md",
diff --git a/packages/boxel-cli/scripts/build-skills.ts b/packages/boxel-cli/scripts/build-skills.ts
index 0f0939b0e1f..0a882b914b3 100644
--- a/packages/boxel-cli/scripts/build-skills.ts
+++ b/packages/boxel-cli/scripts/build-skills.ts
@@ -36,7 +36,7 @@ import {
 import { relative, resolve } from 'path';
 import { format, resolveConfig } from 'prettier';
 
-const BOXEL_SKILLS_VERSION = 'v0.1.0';
+const BOXEL_SKILLS_VERSION = 'v0.1.1';
 const BOXEL_SKILLS_REPO_URL = 'https://github.com/cardstack/boxel-skills.git';
 
 const PLUGIN_DIR = resolve(import.meta.dirname, '..', 'plugin');
diff --git a/packages/bxl/README.md b/packages/bxl/README.md
index 046f337598a..df1c833f026 100644
--- a/packages/bxl/README.md
+++ b/packages/bxl/README.md
@@ -331,14 +331,19 @@ Same string language everywhere. Each slot in the object is a plain string; the
 
 ### Using BXL inside Boxel
 
-In Boxel realms, import the compute factory and syntax tags from the uploaded
-bundle, then assign the returned function to `computeVia`:
+In Boxel realms, import the compute factory and syntax tags from the
+platform module — the host serves `@cardstack/bxl` to card code, and a realm
+that carries its own uploaded bundle imports that bundle by relative path
+instead — then assign the returned function to `computeVia`:
 
 ```ts
-import { expression, fx, jq } from '../bxl';
+import { expression, fx, jq } from '@cardstack/bxl';
 
+// An aggregate's iterating argument has to be collected: function arguments
+// are jq streams, so the uncollected `SUM(LineItems[].Amount)` would run once
+// per line item and hand the field one value per element.
 @field subtotal = contains(NumberField, {
-  computeVia: expression(fx`SUM("Line Item".Amount)`),
+  computeVia: expression(fx`SUM([LineItems[].Amount])`),
 });
 
 @field slug = contains(StringField, {
diff --git a/packages/bxl/docs/syntax-modes.md b/packages/bxl/docs/syntax-modes.md
index 1a4d399bffe..7b555ff6a08 100644
--- a/packages/bxl/docs/syntax-modes.md
+++ b/packages/bxl/docs/syntax-modes.md
@@ -16,13 +16,18 @@ locked down by a case in [`../tests/boxel/`](../tests/boxel/).
 
 ## Using BXL Inside Boxel
 
-In a Boxel realm, import from the uploaded realm bundle using the
-relative path to that bundle:
+In a Boxel realm, import the platform module by its bare specifier —
+the host serves it to card code, and the package root is the
+card-facing entry:
 
 ```ts
-import { expression, fx, jq } from '../bxl';
+import { expression, fx, jq } from '@cardstack/bxl';
 ```
 
+A realm that carries its own uploaded bundle imports that bundle by
+relative path instead (`from '../bxl'`); everything below applies the
+same either way.
+
 `expression` is the same compute factory as `bxl` / `expr`; it returns
 a function shaped for `computeVia`. The factory validates the source against
 the `derive` execution profile when it is constructed, so non-deterministic
@@ -30,7 +35,7 @@ or request-scoped expressions are rejected before Boxel runs the field.
 
 ```ts
 @field subtotal = contains(NumberField, {
-  computeVia: expression(fx`SUM("Line Item".Amount)`),
+  computeVia: expression(fx`SUM([LineItems[].Amount])`),
 });
 
 @field slug = contains(StringField, {
@@ -158,7 +163,7 @@ Watch for:
 ```ts
 expression(fx`ROUND(Salary / 2080, 2)`);
 expression(fx`PatientId & " — " & FirstName & " " & LastName`);
-expression(fx`SUM(Patients[].Billing.RoomCharge)`);
+expression(fx`SUM([Patients[].Billing.RoomCharge])`);
 ```
 
 The compiler treats `` fx`…` `` exactly like a plain string —
@@ -187,6 +192,16 @@ These apply regardless of the tag:
 - **Null-tolerant arithmetic.** `null - 5`, `5 / 0`, `null * x`,
   `null | startswith("a")` all return `null` / `false` instead of
   throwing.
+- **A single-argument aggregate takes a collected array.** Function
+  arguments are jq streams, so `SUM(Claims[].Paid)` calls `SUM` once per
+  claim and yields one output per claim rather than a total. Collect the
+  iterating argument — `SUM([Claims[].Paid])` — or supply a `schema`,
+  which makes implicit iteration collect on its own
+  (`SUM("Line Item"."Line Total")` compiles to
+  `SUM([.lineItems[].lineTotal])`). A comma list is already collected by
+  the compiler (`SUM(Paid, Reserve)` → `SUM([.paid, .reserve])`), and a
+  scalar parameter must not be wrapped: `ROUND([1.234], 2)` hands an
+  array to a function that wants a number.
 
 ## Mixed-syntax expressions
 
diff --git a/packages/bxl/tests/boxel/README.md b/packages/bxl/tests/boxel/README.md
index e064e23e4ec..e0ebe97dc85 100644
--- a/packages/bxl/tests/boxel/README.md
+++ b/packages/bxl/tests/boxel/README.md
@@ -28,6 +28,7 @@ rules, so a failing case name points straight at the one that broke.
 | `fielddef-threading.ts`     | Multi-stage `{ as: Cls }` threading — the insurance pipeline pattern                                                     |
 | `card-source-mutation.ts`   | The card-source mutation adapter: schema derivation, computed-field skips, relationship serialization, stale-plan safety |
 | `update-via-bxl.ts`         | The `updateViaBxl` adapter                                                                                               |
+| `authoring-skill-claims.ts` | Drift guard for the `bxl-authoring` agent skill: every behavior it teaches, plus the repo paths it cites                 |
 
 ## Running
 
diff --git a/packages/bxl/tests/boxel/authoring-skill-claims.ts b/packages/bxl/tests/boxel/authoring-skill-claims.ts
new file mode 100644
index 00000000000..9303575b73d
--- /dev/null
+++ b/packages/bxl/tests/boxel/authoring-skill-claims.ts
@@ -0,0 +1,969 @@
+// Drift guard for the card-authoring skill.
+//
+// The `bxl-authoring` agent skill
+// (packages/boxel-cli/plugin/skills/bxl-authoring/SKILL.md) teaches card
+// authors a set of concrete behaviors — which tag preserves `\(…)`, what the
+// derive profile refuses, how an aggregate reads a collection, what a blank
+// input produces. It ships to authors who cannot run the engine to check, so
+// each behavioral claim is pinned here twice:
+//
+//   1. The snippet the skill shows must still appear in the skill text, so a
+//      rewrite that changes an example has to come through this file.
+//   2. The behavior that snippet claims must still hold against the engine.
+//
+// What that does and does not cover is worth stating plainly, because a guard
+// trusted past its reach is worse than none. It covers the engine behaviors
+// reachable from plain Node: tag dispatch, every derive refusal and every
+// allowed form, the aggregate-collect rules, the blank-input table, sentinel
+// versus non-sentinel failure, the date-function zone sweep, memoization modes,
+// `{ as: … }` shapes, and self-enumeration. Two things it cannot check:
+//
+//   - Prose. A `shows()` snippet proves the example is still on the page, not
+//     that the sentence around it still says the right thing. The reason
+//     columns, the guidance paragraphs, and §7/§10's architectural claims are
+//     read by people, not by this file.
+//   - Anything needing a live card runtime. Query-backed inverse staleness and
+//     the `{ id }` clip across a cycle are pinned by the host integration
+//     suites the skill names, and the last case here asserts those pointers
+//     resolve. §10's stale-paint interaction with Glimmer's render flush is NOT
+//     pinned anywhere — it follows from runloop ordering, and the mitigation
+//     the skill gives (`memoize: false`) is what is pinned.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { deepStrictEqual, ok, strictEqual } from 'node:assert';
+import { join } from 'node:path';
+import {
+  BXL_DERIVE_DENIED_CALLS,
+  evaluateBxl,
+  expression,
+  fx,
+  jq,
+  loadAllFormulaExtensions,
+} from '../../src/index.ts';
+import { categoryForBxlFunction } from '../../src/bxl/profiles/function-safety.ts';
+
+// The host folds every lazy formula family into the default library set before
+// serving `@cardstack/bxl` to card code, so a card reaches `NPV` and `isEmail`
+// as readily as `ROUND`. Do the same here or those cases would assert against a
+// narrower library than the skill's audience has.
+await loadAllFormulaExtensions();
+
+const REPO_ROOT = join(import.meta.dirname, '..', '..', '..', '..');
+const SKILL_PATH = join(
+  REPO_ROOT,
+  'packages/boxel-cli/plugin/skills/bxl-authoring/SKILL.md',
+);
+
+let pass = 0;
+let fail = 0;
+const failures: string[] = [];
+
+function check(name: string, fn: () => void) {
+  try {
+    fn();
+    pass++;
+  } catch (error) {
+    fail++;
+    failures.push(`  ${name}\n    ${(error as Error).message.split('\n')[0]}`);
+  }
+}
+
+if (!existsSync(SKILL_PATH)) {
+  console.log(`FAIL: the authoring skill is not at ${SKILL_PATH}`);
+  process.exit(1);
+}
+const skill = readFileSync(SKILL_PATH, 'utf8');
+// Runs of whitespace collapse, so rewrapping a paragraph or realigning a table
+// column is not a failure — only changing what an example says is.
+const flatten = (text: string) => text.replace(/\s+/g, ' ');
+const skillFlat = flatten(skill);
+
+/** Asserts the skill still shows this snippet. */
+function shows(snippet: string) {
+  ok(
+    skillFlat.includes(flatten(snippet)),
+    `the skill no longer shows \`${snippet}\` — update this case with it`,
+  );
+}
+
+/**
+ * The names the paragraph introduced by `lead` lists, read as its backticked
+ * spans. Exact tokens rather than substrings: `env` must not be satisfied by
+ * some longer word that happens to contain it, and a name must not count as
+ * listed because it appears inside a neighbouring code span.
+ */
+function listedNames(lead: string): string[] {
+  const start = skill.indexOf(lead);
+  ok(start !== -1, `the skill no longer has a "${lead}" paragraph`);
+  const end = skill.indexOf('\n\n', start);
+  const body = flatten(skill.slice(start, end === -1 ? undefined : end));
+  return Array.from(body.matchAll(/`([^`]+)`/g), (match) => match[1].trim());
+}
+
+/**
+ * Asserts the paragraph lists exactly `covered` — every name the cases below
+ * exercise, and nothing else. An entry added to the skill without a case, moved
+ * between the two lists, or dropped from either fails here.
+ */
+function listsExactly(lead: string, covered: Array<string | string[]>) {
+  deepStrictEqual(
+    listedNames(lead).sort(),
+    covered.flat().sort(),
+    `the "${lead}" list and this suite's cases have diverged`,
+  );
+}
+
+const REFUSED_LEAD = 'Refused: volatile calls';
+const ALLOWED_LEAD = 'Allowed and useful:';
+
+// ------------------------------------------------- tag dispatch
+
+check('a plain string drops the backslash before `(`', () => {
+  shows('expression(\'"\\(.bpSystolic)/\\(.bpDiastolic)"\')');
+  // The escape is the subject of the case, so the source is spelled the way an
+  // author spells it and the assertion below shows what JS hands on.
+  // eslint-disable-next-line no-useless-escape -- the useless escape IS the trap
+  const asAuthorTyped = '"\(.bpSystolic)/\(.bpDiastolic)"';
+  strictEqual(
+    evaluateBxl(asAuthorTyped, { bpSystolic: 120, bpDiastolic: 80 }).value,
+    '(.bpSystolic)/(.bpDiastolic)',
+    'the interpolation is inert, and nothing throws to say so',
+  );
+});
+
+check('either tag preserves the interpolation', () => {
+  shows('expression(jq`"\\(.bpSystolic)/\\(.bpDiastolic)"`)');
+  shows('Either tag preserves it — both read the raw strings');
+  const bp = { bpSystolic: 120, bpDiastolic: 80 };
+  strictEqual(
+    expression(jq`"\(.bpSystolic)/\(.bpDiastolic)"`).call(bp),
+    '120/80',
+  );
+  strictEqual(
+    expression(fx`"\(.bpSystolic)/\(.bpDiastolic)"`).call(bp),
+    '120/80',
+    'fx reads String.raw too, so the checklist must say tagged, not jq-tagged',
+  );
+});
+
+check('a PascalCase label inside an interpolation is not resolved', () => {
+  shows("throws `'PaidAmount/0' is not defined` the first");
+  shows('Write the path — `` fx`"\\(.paidAmount) paid"` ``');
+  const card = { paidAmount: 10 };
+  // Construction is fine either way; the failure waits for the first read.
+  const unresolved = expression(fx`"\(PaidAmount) paid"`);
+  let message = '';
+  try {
+    unresolved.call(card);
+  } catch (error) {
+    message = (error as Error).message;
+  }
+  ok(
+    message.includes(`'PaidAmount/0' is not defined`),
+    `expected an undefined-function throw, got: ${message.split('\n')[0]}`,
+  );
+  strictEqual(
+    expression(fx`"\(.paidAmount) paid"`).call(card),
+    '10 paid',
+    'the path spelling is what works',
+  );
+});
+
+check('the tag table rows still read true', () => {
+  // The "Why" column is the reason an author picks a tag, so it is pinned with
+  // the row rather than left to prose.
+  shows(
+    '| `\\(…)` jq interpolation                     | `` jq`…` ``     | A plain string drops the backslash — see trap 4        |',
+  );
+  shows(
+    '| Bare PascalCase field labels (`PaidAmount`) | `` fx`…` ``     | The compiler resolves them to `.paidAmount`            |',
+  );
+  shows(
+    '| Quoted multi-word labels (`"Line Item"`)    | `fx` + `schema` | Label resolution needs the schema — see trap 3         |',
+  );
+  strictEqual(expression(fx`PaidAmount`).bxl.compiledSource, '.paidAmount');
+  strictEqual(
+    expression('PaidAmount').bxl.compiledSource,
+    '.paidAmount',
+    'a plain string compiles like fx, which the row below the table states',
+  );
+});
+
+check('IF is the Excel function, if/then/end is the jq construct', () => {
+  shows(
+    '`IF(cond, t, f)` is the Excel function, `if cond then … end` is the jq',
+  );
+  strictEqual(
+    expression(fx`IF(.status == "Open", 1, 0)`).call({ status: 'Open' }),
+    1,
+  );
+  strictEqual(
+    expression(fx`if Status == "Open" then 1 else 0 end`).call({
+      status: 'Open',
+    }),
+    1,
+  );
+});
+
+// ------------------------------------------------- the derive profile
+
+/** The diagnostic code `expression()` throws for a rejected source. */
+function rejectionCode(make: () => unknown): string {
+  try {
+    make();
+  } catch (error) {
+    const match = /derive-[a-z-]+/.exec((error as Error).message);
+    if (match) return match[0];
+    return `no derive code in: ${(error as Error).message.split('\n')[0]}`;
+  }
+  return 'accepted';
+}
+
+check('the diagnostic the skill quotes is the one the factory throws', () => {
+  shows(
+    'derive-call-banned: Profile.derive is for deterministic write/index-time',
+  );
+  shows('cannot use call TODAY: volatile calls are not stable write-time');
+  let message = '';
+  try {
+    expression(fx`TODAY()`);
+  } catch (error) {
+    message = (error as Error).message;
+  }
+  ok(
+    message.startsWith('computeVia expression violates the derive profile:'),
+    `unexpected preamble: ${message.split('\n')[0]}`,
+  );
+  ok(
+    message.includes(
+      'derive-call-banned: Profile.derive is for deterministic write/index-time computation and cannot use call TODAY: volatile calls are not stable write-time derivations.',
+    ),
+    'the quoted diagnostic no longer matches',
+  );
+});
+
+check('every call the skill lists as refused is refused', () => {
+  shows(
+    'Refused: volatile calls (`TODAY`, `NOW`, `RAND`, `RANDBETWEEN`, and the two clock-reading validator helpers `isAfter` / `isBefore`)',
+  );
+  shows('Compare two stored dates with the operators instead');
+  // Each entry: the names it covers in the skill's list, a source that reaches
+  // them, and the diagnostic code the factory must answer with.
+  const refused: Array<[string | string[], () => unknown, string]> = [
+    ['TODAY', () => expression(fx`TODAY()`), 'derive-call-banned'],
+    ['NOW', () => expression(fx`NOW()`), 'derive-call-banned'],
+    ['RAND', () => expression(fx`RAND()`), 'derive-call-banned'],
+    [
+      'RANDBETWEEN',
+      () => expression(fx`RANDBETWEEN(1, 6)`),
+      'derive-call-banned',
+    ],
+    ['@User', () => expression(fx`@User.id`), 'derive-context-banned'],
+    ['@Env', () => expression(fx`@Env.region`), 'derive-context-banned'],
+    ['$new', () => expression(fx`$new.total`), 'derive-context-banned'],
+    ['$old', () => expression(fx`$old.total`), 'derive-context-banned'],
+    ['def', () => expression(jq`def f: . + 1; f`), 'derive-def-banned'],
+    [
+      ['try', 'catch'],
+      () => expression(jq`try .a catch "x"`),
+      'derive-try-banned',
+    ],
+    ['error', () => expression(jq`error("boom")`), 'derive-call-banned'],
+    [
+      ['label', 'break'],
+      () => expression(jq`label $out | .a, break $out`),
+      'derive-control-flow-banned',
+    ],
+    ['=', () => expression(jq`.total = 5`), 'derive-assignment-banned'],
+    ['|=', () => expression(jq`.total |= . + 1`), 'derive-assignment-banned'],
+    [
+      '..',
+      () => expression(jq`.. | numbers`),
+      'derive-recursive-descent-banned',
+    ],
+    ['@csv', () => expression(jq`[.a, .b] | @csv`), 'derive-format-banned'],
+    ['debug', () => expression(jq`debug`), 'derive-call-banned'],
+    ['env', () => expression(jq`env`), 'derive-call-banned'],
+    ['stderr', () => expression(jq`stderr`), 'derive-call-banned'],
+    ['halt', () => expression(jq`halt`), 'derive-call-banned'],
+    ['input', () => expression(jq`input`), 'derive-call-banned'],
+    ['builtins', () => expression(jq`builtins | length`), 'derive-call-banned'],
+    [
+      'isAfter',
+      () => expression(fx`isAfter(StartDate, EndDate)`),
+      'derive-call-banned',
+    ],
+    [
+      'isBefore',
+      () => expression(fx`isBefore(StartDate, EndDate)`),
+      'derive-call-banned',
+    ],
+  ];
+  listsExactly(
+    REFUSED_LEAD,
+    refused.map(([names]) => names),
+  );
+  for (const [names, make, code] of refused) {
+    strictEqual(rejectionCode(make), code, `${names} should be ${code}`);
+  }
+});
+
+/**
+ * Call names the `derive` profile bans that the skill deliberately does not
+ * name, each with the category its refusal falls under. The skill states those
+ * categories — "control and side-effect calls", "runtime metadata" — and names
+ * the members an author might plausibly reach for; these are the rest.
+ *
+ * This list exists so the case below can be anchored to the engine instead of
+ * to this suite. Comparing the skill's list against the cases above alone is a
+ * closed loop: a ban neither of them enumerated is invisible to both, which is
+ * how `isAfter` / `isBefore` stayed missing from a page that blessed the
+ * validator helpers they sit among.
+ */
+const REFUSALS_NOT_WORTH_NAMING = new Map<string, string>([
+  ['HALT_ERROR', 'controlOrSideEffect'],
+  ['INPUT_FILENAME', 'controlOrSideEffect'],
+  ['INPUT_LINE_NUMBER', 'controlOrSideEffect'],
+  ['GET_JQ_ORIGIN', 'metadata'],
+  ['GET_PROG_ORIGIN', 'metadata'],
+  ['GET_SEARCH_LIST', 'metadata'],
+  // Not a name a card author can even reach: the parser rejects it as an
+  // unexpected keyword before the profile gets a say.
+  ['MODULEMETA', 'metadata'],
+]);
+
+check('the skill accounts for every call the derive profile bans', () => {
+  const listed = new Set(
+    listedNames(REFUSED_LEAD).map((name) => name.toUpperCase()),
+  );
+  const unaccounted: string[] = [];
+  for (const denied of BXL_DERIVE_DENIED_CALLS) {
+    if (listed.has(denied)) continue;
+    const waived = REFUSALS_NOT_WORTH_NAMING.get(denied);
+    if (waived) {
+      // A waiver is only honest while the ban really falls under the category
+      // the skill describes it by.
+      strictEqual(
+        categoryForBxlFunction(denied),
+        waived,
+        `${denied} is waived as ${waived} but the engine classes it otherwise`,
+      );
+      continue;
+    }
+    unaccounted.push(denied);
+  }
+  deepStrictEqual(
+    unaccounted,
+    [],
+    `the derive profile bans these and the skill neither names nor waives them: ${unaccounted.join(', ')}`,
+  );
+});
+
+check(
+  'every form the skill lists as allowed runs and produces its value',
+  () => {
+    shows('Allowed and useful: `IFERROR` / `IFNA` · optional access (`.a?`)');
+    // Constructing proves nothing on its own: the derive profile only screens the
+    // names it bans, so a name the registry has never heard of constructs too.
+    // Each of these therefore evaluates, and an unknown name is the control.
+    const card = {
+      amount: 4,
+      claims: [{ paid: 10 }, { paid: 5 }],
+      cashFlows: [-100, 60, 60],
+      email: 'ops@example.com',
+      items: [1, 2, 3],
+      startDate: '2026-04-30',
+      status: 'Open',
+      a: 7,
+    };
+    const allowed: Array<[string | string[], () => unknown, unknown]> = [
+      ['IFERROR', () => expression(fx`IFERROR(Amount, 0)`).call(card), 4],
+      ['IFNA', () => expression(fx`IFNA(Amount, 0)`).call(card), 4],
+      ['.a?', () => expression(jq`.a?`).call(card), 7],
+      ['SUM', () => expression(fx`SUM([Claims[].Paid])`).call(card), 15],
+      [
+        'AVERAGE',
+        () => expression(fx`AVERAGE([Claims[].Paid])`).call(card),
+        7.5,
+      ],
+      ['COUNT', () => expression(fx`COUNT([Claims[].Paid])`).call(card), 2],
+      [
+        'NPV',
+        () => expression(fx`ROUND(NPV(0.1, CashFlows), 4)`).call(card),
+        3.7566,
+      ],
+      ['isEmail', () => expression(fx`isEmail(Email)`).call(card), true],
+      ['isDate', () => expression(fx`isDate(StartDate)`).call(card), true],
+      [
+        'LET',
+        () => expression(fx`LET(t, SUM([Claims[].Paid]), t > 100)`).call(card),
+        false,
+      ],
+      ['. as $x | …', () => expression(jq`. as $x | $x.a`).call(card), 7],
+      [
+        'reduce',
+        () => expression(jq`reduce .items[] as $i (0; . + $i)`).call(card),
+        6,
+      ],
+      [
+        'foreach',
+        () =>
+          expression(jq`[foreach .items[] as $i (0; . + $i)] | last`).call(
+            card,
+          ),
+        6,
+      ],
+      [
+        'group_by',
+        () => expression(jq`[.claims[]] | group_by(.paid) | length`).call(card),
+        2,
+      ],
+      [
+        'unique',
+        () => expression(jq`[.claims[] | .paid] | unique | length`).call(card),
+        2,
+      ],
+      ['to_entries', () => expression(jq`to_entries | length`).call(card), 8],
+      ['keys', () => expression(jq`keys | length`).call(card), 8],
+      ['tojson', () => expression(jq`tojson | length > 0`).call(card), true],
+    ];
+    listsExactly(
+      ALLOWED_LEAD,
+      allowed.map(([names]) => names),
+    );
+    for (const [names, run, expected] of allowed) {
+      // One evaluation per case: a throw and a wrong value are distinguished by
+      // where this lands, not by running the source twice.
+      let value: unknown;
+      try {
+        value = run();
+      } catch (error) {
+        throw new Error(
+          `${names} threw instead of evaluating: ${(error as Error).message.split('\n')[0]}`,
+        );
+      }
+      strictEqual(value, expected, `${names} produced the wrong value`);
+    }
+
+    const unknown = expression(fx`TOTALLYFAKE(1)`);
+    let controlMessage = '';
+    try {
+      unknown.call(card);
+    } catch (error) {
+      controlMessage = (error as Error).message;
+    }
+    ok(
+      controlMessage.includes('is not defined'),
+      'control: an unknown function name must fail on read, or the cases above prove nothing',
+    );
+  },
+);
+
+// ------------------------------------------------- aggregates over collections
+
+const twoClaims = { claims: [{ paid: 10 }, { paid: 5 }] };
+
+check('an aggregate over a stream runs per element', () => {
+  shows(
+    '// WRONG — compiles to SUM(.claims[].paid); with two claims the field gets [10, 5]',
+  );
+  const compute = expression(fx`SUM(Claims[].Paid)`);
+  strictEqual(compute.bxl.compiledSource, 'SUM(.claims[].paid)');
+  deepStrictEqual(compute.call(twoClaims), [10, 5]);
+});
+
+check('collecting first aggregates once', () => {
+  shows('computeVia: expression(fx`SUM([Claims[].Paid])`);');
+  const compute = expression(fx`SUM([Claims[].Paid])`);
+  strictEqual(compute.bxl.compiledSource, 'SUM([.claims[].paid])');
+  strictEqual(compute.call(twoClaims), 15);
+});
+
+check('the WRONG example is the uncollected one', () => {
+  // Pinning the two code lines against their comments, not just the sources:
+  // swapping them would otherwise leave both snippets on the page and teach the
+  // exact inverse of the trap.
+  shows(
+    '// WRONG — compiles to SUM(.claims[].paid); with two claims the field gets [10, 5]\ncomputeVia: expression(fx`SUM(Claims[].Paid)`);',
+  );
+  shows(
+    '// RIGHT — collect first, then aggregate: 15\ncomputeVia: expression(fx`SUM([Claims[].Paid])`);',
+  );
+  shows(
+    '// RIGHT — the jq spelling, with a fallback for the empty case\ncomputeVia: expression(jq`[.claims[] | .paidAmount] | add // 0`);',
+  );
+  const compute = expression(jq`[.claims[] | .paidAmount] | add // 0`);
+  strictEqual(compute.call({ claims: [] }), 0);
+  strictEqual(
+    compute.call({ claims: [{ paidAmount: 10 }, { paidAmount: 5 }] }),
+    15,
+  );
+});
+
+check('the collect rule is only for the argument that iterates', () => {
+  shows('Collect **the argument that iterates**, and only that one');
+  shows(
+    '`SUM(Amounts)` over a `containsMany(NumberField)` is correct as it stands',
+  );
+  strictEqual(
+    expression(fx`SUM(Amounts)`).call({ amounts: [10, 5] }),
+    15,
+    'an array-valued field is one value already',
+  );
+
+  shows('`SUM(Paid, Reserve)` compiles to');
+  shows('`SUM([.paid, .reserve])`, and even `SUM(Claims[].Paid, 0)` becomes');
+  shows('`SUM([.claims[].paid, 0])`');
+  strictEqual(
+    expression(fx`SUM(Paid, Reserve)`).bxl.compiledSource,
+    'SUM([.paid, .reserve])',
+  );
+  const multiArg = expression(fx`SUM(Claims[].Paid, 0)`);
+  strictEqual(multiArg.bxl.compiledSource, 'SUM([.claims[].paid, 0])');
+  strictEqual(
+    multiArg.call(twoClaims),
+    15,
+    'a comma list collects, so the multi-argument spelling never showed the trap',
+  );
+
+  shows('**Never wrap a scalar parameter.** `ROUND([1.234], 2)` and');
+  shows(
+    '`NPV([0.1], CashFlows)` hand an array to a function that wants a number',
+  );
+  strictEqual(
+    expression(fx`ROUND([1.234], 2)`).call({}),
+    null,
+    'a wrapped scalar blanks the field',
+  );
+  strictEqual(
+    expression(fx`NPV([0.1], CashFlows)`).call({ cashFlows: [-100, 60, 60] }),
+    null,
+  );
+  strictEqual(
+    expression(fx`ROUND(NPV(0.1, CashFlows), 4)`).call({
+      cashFlows: [-100, 60, 60],
+    }),
+    3.7566,
+    'unwrapped, the same call works',
+  );
+});
+
+check('a schema makes implicit iteration collect on its own', () => {
+  shows('`SUM("Line Item"."Line Total")` compiles to');
+  shows('`SUM([.lineItems[].lineTotal])`');
+  const schema = {
+    fields: [
+      {
+        key: 'lineItems',
+        label: 'Line Item',
+        kind: 'array' as const,
+        item: { fields: [{ key: 'lineTotal', label: 'Line Total' }] },
+      },
+    ],
+  };
+  const run = evaluateBxl(
+    'SUM("Line Item"."Line Total")',
+    { lineItems: [{ lineTotal: 10 }, { lineTotal: 5 }] },
+    { schema },
+  );
+  strictEqual(run.compiledSource, 'SUM([.lineItems[].lineTotal])');
+  strictEqual(run.value, 15);
+});
+
+check('a quoted label with no schema fails loudly', () => {
+  shows('loudly (`Cannot index string with string`)');
+  let message = '';
+  try {
+    evaluateBxl('SUM("Line Item"."Line Total")', { lineItems: [] });
+  } catch (error) {
+    message = (error as Error).message;
+  }
+  ok(
+    message.includes('Cannot index string with string'),
+    `unexpected message: ${message.split('\n')[0]}`,
+  );
+});
+
+check('the factory exposes the compiled jq and the dependency list', () => {
+  shows(
+    "// { source, compiledSource: 'SUM([.claims[].paid])', warnings, deps, memoize }",
+  );
+  const meta = expression(fx`SUM([Claims[].Paid])`).bxl;
+  strictEqual(meta.source, 'SUM([Claims[].Paid])');
+  strictEqual(meta.compiledSource, 'SUM([.claims[].paid])');
+  deepStrictEqual([...meta.deps], ['claims']);
+  strictEqual(meta.memoize, 'microtask');
+});
+
+// ------------------------------------------------- blank inputs
+
+const noAmounts = {};
+
+check('the blank-input table still reads true', () => {
+  // Whole rows, reason column included: the stated mechanism is as much a claim
+  // as the value, and a wrong mechanism is what sends an author down a wrong fix.
+  const rows: Array<[string, () => unknown, unknown]> = [
+    [
+      '| `` fx`Paid + Reserve` ``              | `null`  | null propagates through arithmetic          |',
+      () => expression(fx`Paid + Reserve`).call(noAmounts),
+      null,
+    ],
+    [
+      '| `` fx`Paid + 5` ``                    | `5`     | a null addend contributes nothing           |',
+      () => expression(fx`Paid + 5`).call(noAmounts),
+      5,
+    ],
+    [
+      '| `` fx`SUM(Paid, Reserve)` ``          | `0`     | aggregates skip blanks, Excel-style         |',
+      () => expression(fx`SUM(Paid, Reserve)`).call(noAmounts),
+      0,
+    ],
+    [
+      '| `` fx`ROUND(Paid + Reserve)` ``       | `0`     | `ROUND` absorbs a null operand              |',
+      () => expression(fx`ROUND(Paid + Reserve)`).call(noAmounts),
+      0,
+    ],
+    [
+      '| `` fx`Premium / 0` ``                 | `null`  | division by zero yields null, not `#DIV/0!` |',
+      () => expression(fx`Premium / 0`).call({ premium: 100 }),
+      null,
+    ],
+    [
+      '| `` jq`[.claims[] \\| .paid] \\| add` `` | `null`  | `add` over an empty array is null           |',
+      () => expression(jq`[.claims[] | .paid] | add`).call({ claims: [] }),
+      null,
+    ],
+    [
+      '| `` jq`.name \\| startswith("a")` ``    | `false` | string predicates on null are false         |',
+      () => expression(jq`.name | startswith("a")`).call(noAmounts),
+      false,
+    ],
+  ];
+  for (const [row, run, expected] of rows) {
+    shows(row);
+    strictEqual(run(), expected, `row changed: ${row}`);
+  }
+});
+
+check('`//` guards a blank operand', () => {
+  shows('`(Paid // 0) + (Reserve // 0)`');
+  strictEqual(expression(fx`(Paid // 0) + (Reserve // 0)`).call(noAmounts), 0);
+});
+
+check('IFERROR does not rescue a division by zero', () => {
+  shows('`IFERROR` does **not** rescue it — guard the divisor instead');
+  strictEqual(
+    expression(fx`IFERROR(Premium / 0, 0)`).call({ premium: 100 }),
+    null,
+  );
+});
+
+check('`&` renders a blank operand as the text null', () => {
+  shows('yields `Acme (null)`');
+  strictEqual(
+    expression(fx`Name & " (" & Tier & ")"`).call({ name: 'Acme' }),
+    'Acme (null)',
+  );
+  shows('fx`Name & " (" & (Tier // "") & ")"`');
+  strictEqual(
+    expression(fx`Name & " (" & (Tier // "") & ")"`).call({ name: 'Acme' }),
+    'Acme ()',
+  );
+  shows('use `CONCAT` / `TEXTJOIN`, which');
+  strictEqual(
+    expression(fx`CONCAT(Name, "-", Tier)`).call({ name: 'Acme' }),
+    'Acme-',
+  );
+  strictEqual(
+    expression(fx`TEXTJOIN("-", TRUE, Name, Tier)`).call({ name: 'Acme' }),
+    'Acme',
+  );
+});
+
+// ------------------------------------------------- Excel error sentinels
+
+check('an uncaught sentinel lands as null, not a throw', () => {
+  shows('caught at the factory boundary, which returns `null`');
+  shows('`` fx`INDEX(Rows, 99)` `` leaves one blank field');
+  strictEqual(expression(fx`NA()`).call(noAmounts), null);
+  strictEqual(expression(fx`INDEX(Rows, 99)`).call({ rows: [1, 2, 3] }), null);
+  // Every sentinel the skill names has to be one this engine actually raises,
+  // or an author waits for an error that never comes. #NAME? is deliberately
+  // absent from that list: nothing throws it, and the failure it stands for in
+  // a spreadsheet — an unknown function — is the non-sentinel case below.
+  for (const sentinel of ['#N/A', '#DIV/0!', '#VALUE!', '#REF!', '#NUM!']) {
+    shows(sentinel);
+  }
+  ok(
+    !skillFlat.includes('#NAME?'),
+    'the skill lists #NAME?, which this engine never raises',
+  );
+});
+
+check('a sentinel blanks the whole expression, not just its own call', () => {
+  shows('`` fx`ROUND(NA()) + 5` `` is null, not 5');
+  shows('even though `ROUND` absorbs a null operand');
+  strictEqual(
+    expression(fx`ROUND(Paid) + 5`).call(noAmounts),
+    5,
+    'a null operand is absorbed by ROUND, so the addition still runs',
+  );
+  strictEqual(
+    expression(fx`ROUND(NA()) + 5`).call(noAmounts),
+    null,
+    'a sentinel propagates out of ROUND and blanks the field',
+  );
+});
+
+check(
+  'a non-sentinel failure fails the card instead of blanking a field',
+  () => {
+    shows("gives `'SUMM/1' is not defined`");
+    shows('surface as an indexing error on the instance, not as a blank field');
+    // A misspelled name passes the profile check — nothing validates that a name
+    // exists — and throws on first read, which is what reaches the indexer.
+    const misspelled = expression(fx`SUMM([Amounts])`);
+    let message = '';
+    try {
+      misspelled.call({ amounts: [1, 2] });
+    } catch (error) {
+      message = (error as Error).message;
+    }
+    ok(
+      message.includes(`'SUMM/1' is not defined`),
+      `expected an undefined-function throw, got: ${message.split('\n')[0] || '(no throw)'}`,
+    );
+
+    shows('(`` jq`unique` `` over an object rather than an array)');
+    let structuralMessage = '';
+    try {
+      expression(jq`unique`).call({ a: 1 });
+    } catch (error) {
+      structuralMessage = (error as Error).message;
+    }
+    ok(
+      structuralMessage.length > 0,
+      'a structural op on the wrong shape must throw rather than blank the field',
+    );
+  },
+);
+
+check('the catch-it-deliberately examples still work', () => {
+  shows('fx`IFERROR(VLOOKUP(Sku, Rows, 2, FALSE), "unlisted")`');
+  strictEqual(
+    expression(fx`IFERROR(VLOOKUP(Sku, Rows, 2, FALSE), "unlisted")`).call({
+      sku: 'x',
+      rows: [],
+    }),
+    'unlisted',
+  );
+  shows('fx`IFNA(NA(), "none")`');
+  strictEqual(expression(fx`IFNA(NA(), "none")`).call(noAmounts), 'none');
+  shows('An `AVERAGE` over an empty collection raises');
+  strictEqual(
+    expression(fx`AVERAGE([Claims[].Paid])`).call({ claims: [] }),
+    null,
+  );
+});
+
+// ------------------------------------------------- dates
+
+check('the date functions the skill calls safe agree across host zones', () => {
+  shows('`DATE`, `EDATE`, `EOMONTH`, `WEEKDAY`, `DATEVALUE`, `YEARFRAC`,');
+  shows('`DAYS`, `NETWORKDAYS` and friends give one answer across host zones');
+  const sources = [
+    'DATE(2026, 2, 5)',
+    'EDATE(DATE(2026, 2, 5), 1)',
+    'EOMONTH(DATE(2026, 2, 5), 1)',
+    'WEEKDAY(DATE(2026, 4, 30))',
+    'DATEVALUE("April 30, 2026 23:30")',
+    'YEARFRAC(DATE(2026, 1, 31), DATE(2026, 3, 31), 0)',
+    'DAYS(DATE(2026, 4, 30), DATE(2026, 4, 22))',
+    'NETWORKDAYS(DATE(2026, 4, 1), DATE(2026, 4, 30))',
+  ];
+  // The whole-suite sweep in tests/unit/fixtures/function-coverage runs every
+  // registry case under six zones; these two are the pair that moved a
+  // calendar day apart when the anchoring was wrong.
+  const zones = ['UTC', 'Pacific/Kiritimati'];
+  const original = process.env.TZ;
+  try {
+    const perZone = zones.map((zone) => {
+      process.env.TZ = zone;
+      return sources.map((source) => evaluateBxl(source, null).value);
+    });
+    deepStrictEqual(
+      perZone[0],
+      perZone[1],
+      `a date function answers differently under ${zones[1]}`,
+    );
+  } finally {
+    if (original === undefined) delete process.env.TZ;
+    else process.env.TZ = original;
+  }
+});
+
+check('TODAY and NOW are unavailable in a computed', () => {
+  shows('`TODAY` and `NOW` are not available in a computed at all');
+  strictEqual(
+    rejectionCode(() => expression(fx`TODAY()`)),
+    'derive-call-banned',
+  );
+  strictEqual(
+    rejectionCode(() => expression(fx`NOW()`)),
+    'derive-call-banned',
+  );
+});
+
+// ------------------------------------------------- memoization
+
+check('memoize: false re-runs on every read', () => {
+  shows('memoize: false,');
+  const card = { status: 'Open' };
+  const memoized = expression(jq`{ label: .status }`);
+  strictEqual(
+    memoized.call(card),
+    memoized.call(card),
+    'the default caches within the microtask',
+  );
+  const fresh = expression(jq`{ label: .status }`, { memoize: false });
+  ok(
+    fresh.call(card) !== fresh.call(card),
+    'memoize: false should hand back a new value each read',
+  );
+});
+
+// ------------------------------------------------- { as: FieldDef }
+
+check(
+  '{ as: … } materializes objects and array elements, passes scalars',
+  () => {
+    shows('Scalars and null pass through untouched');
+    class RiskBand {
+      label?: string;
+      score?: number;
+    }
+    const single = expression(jq`{ label: "High", score: 8 }`, {
+      as: RiskBand,
+    });
+    const band = single.call({}) as RiskBand;
+    ok(band instanceof RiskBand, 'an object output becomes an instance');
+    strictEqual(band.label, 'High');
+
+    const many = expression(jq`[{ label: "a" }, { label: "b" }]`, {
+      as: RiskBand,
+    });
+    const bands = many.call({}) as RiskBand[];
+    strictEqual(bands.length, 2);
+    ok(
+      bands.every((entry) => entry instanceof RiskBand),
+      'every element is materialized',
+    );
+
+    strictEqual(
+      expression(jq`.subtotal`, { as: RiskBand }).call({ subtotal: 3 }),
+      3,
+      'a scalar passes through',
+    );
+    strictEqual(
+      expression(jq`.missing`, { as: RiskBand }).call({}),
+      null,
+      'null passes through',
+    );
+  },
+);
+
+// ------------------------------------------------- self-referential compute
+
+/**
+ * Installs `source` as a computed getter on a record and reads it, counting how
+ * many times the getter is entered — one entry is the read itself, a second is
+ * the program re-entering the field it is producing.
+ */
+function selfRead(source: unknown) {
+  const compute = expression(source as never);
+  let entries = 0;
+  const record: Record<string, unknown> = {
+    a: 1,
+    get derived() {
+      entries += 1;
+      return compute.call(this);
+    },
+  };
+  try {
+    return { value: record.derived, entries, threw: false };
+  } catch (error) {
+    return { value: (error as Error).message, entries, threw: true };
+  }
+}
+
+check(
+  'reading a record’s own values re-enters and reads the field blank',
+  () => {
+    shows('`` jq`tojson` `` on a card yields `{"a":1,"derived":null}`');
+    const serialized = selfRead(jq`tojson`);
+    strictEqual(serialized.threw, false);
+    strictEqual(serialized.value, '{"a":1,"derived":null}');
+    strictEqual(serialized.entries, 2, 'the program re-entered the field');
+  },
+);
+
+check('`keys` reads field names, so nothing re-enters', () => {
+  shows('it reads the field names, never their values, so nothing re-enters');
+  const named = selfRead(jq`keys`);
+  strictEqual(named.threw, false);
+  deepStrictEqual(named.value, ['a', 'derived']);
+  strictEqual(named.entries, 1, 'no re-entry — the values were never read');
+});
+
+check('`unique` over a record throws rather than reading blank', () => {
+  shows('is not a self-reference problem at all — it throws, because `unique`');
+  const deduped = selfRead(jq`unique`);
+  strictEqual(deduped.threw, true, 'unique over an object must throw');
+});
+
+// ------------------------------------------------- the skill's own pointers
+
+check('every repo path the skill cites exists', () => {
+  const cited = new Set(
+    Array.from(
+      skill.matchAll(/`(packages\/[A-Za-z0-9._/-]+)`/g),
+      (match) => match[1],
+    ),
+  );
+  // A floor on the count would let a citation be dropped silently, so the
+  // pointers the skill's pinned-rules list is built on are named here.
+  for (const required of [
+    'packages/bxl/tests/boxel/authoring-skill-claims.ts',
+    'packages/host/tests/helpers/cards/bxl-tracking.ts',
+    'packages/host/tests/integration/bxl-expression-test.gts',
+    'packages/host/tests/integration/bxl-platform-module-test.gts',
+    'packages/host/tests/integration/bxl-cyclic-graph-test.gts',
+    'packages/bxl/tests/boxel/',
+    'packages/bxl/docs/',
+  ]) {
+    ok(cited.has(required), `the skill no longer cites ${required}`);
+  }
+  for (const path of cited) {
+    ok(existsSync(join(REPO_ROOT, path)), `the skill cites a missing ${path}`);
+  }
+  // The docs are cited by bare filename, relative to the `packages/bxl/docs/`
+  // entry above, so a rename there would otherwise slip through.
+  for (const doc of Array.from(
+    skill.matchAll(/`([a-z-]+\.md)`/g),
+    (match) => match[1],
+  )) {
+    ok(
+      existsSync(join(REPO_ROOT, 'packages/bxl/docs', doc)),
+      `the skill cites a missing packages/bxl/docs/${doc}`,
+    );
+  }
+});
+
+// ----------------------------------------------------------------
+
+console.log(`BXL authoring-skill claims: ${pass}/${pass + fail} cases passed`);
+if (fail > 0) {
+  console.log('Failures:');
+  for (const f of failures) console.log(f);
+  process.exit(1);
+}