diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts
index 30786ec08c6..9eda0fec401 100644
--- a/packages/base/card-api.gts
+++ b/packages/base/card-api.gts
@@ -2,7 +2,12 @@ import Modifier from 'ember-modifier';
 import GlimmerComponent from '@glimmer/component';
 import { isEqual } from 'lodash-es';
 import { WatchedArray, rawArrayValues } from './watched-array';
-import { BoxelInput, CopyButton } from '@cardstack/boxel-ui/components';
+import {
+  BoxelInput,
+  BrokenLinkTemplate,
+  CopyButton,
+  type BrokenLinkFormat,
+} from '@cardstack/boxel-ui/components';
 import {
   markdownEscape,
   type MenuItemOptions,
@@ -97,6 +102,7 @@ import {
   type RealmResourceIdentifier,
   type VirtualNetwork,
   isDirectIndexedFieldKey,
+  cardTypeName,
 } from '@cardstack/runtime-common';
 import {
   captureQueryFieldSeedData,
@@ -113,9 +119,6 @@ import DefaultCardDefTemplate from './default-templates/isolated-and-edit';
 import DefaultAtomViewTemplate from './default-templates/atom';
 import DefaultHeadTemplate from './default-templates/head';
 import MissingTemplate from './default-templates/missing-template';
-import BrokenLinkTemplate, {
-  type BrokenLinkFormat,
-} from './default-templates/broken-link-template';
 import FieldDefEditTemplate from './default-templates/field-edit';
 import MarkdownTemplate from './default-templates/markdown';
 import DefaultMarkdownFallbackTemplate from './default-templates/markdown-fallback';
@@ -1611,6 +1614,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
                   @errorDoc={{broken.errorDoc}}
                   @state={{broken.kind}}
                   @format={{brokenLinkFormat @format defaultFormats.cardDef}}
+                  @displayName={{cardTypeName broken.reference}}
                   @viewCard={{cardCrudFunctions.viewCard}}
                   ...attributes
                 />
diff --git a/packages/base/codemirror-editor.gts b/packages/base/codemirror-editor.gts
index 13f14100dd7..46afcde3bcc 100644
--- a/packages/base/codemirror-editor.gts
+++ b/packages/base/codemirror-editor.gts
@@ -657,7 +657,10 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
     this._embedPopoverOpen = false;
     let result;
     try {
-      result = await chooseMarkdownEmbed({ defaultTab });
+      result = await chooseMarkdownEmbed({
+        defaultTab,
+        documentBaseUrl: this.args.cardReferenceBaseUrl ?? undefined,
+      });
     } catch (e) {
       // Bridge not registered (e.g. card running outside the host) — silently
       // no-op so the toolbar click doesn't blow up the editor.
@@ -684,12 +687,10 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
         // Resolve the directive's raw ref (which may be relative to the field's
         // base URL) to an absolute URL. The chooser loads the preview via
         // `store.get`, which can't resolve a relative specifier on its own.
-        url: resolveUrl(
-          ref.url,
-          this.args.cardReferenceBaseUrl,
-        ),
+        url: resolveUrl(ref.url, this.args.cardReferenceBaseUrl),
         sizeSpec: ref.sizeSpec,
         kind: ref.kind,
+        documentBaseUrl: this.args.cardReferenceBaseUrl ?? undefined,
       });
     } catch (e) {
       console.warn('markdown-embed chooser unavailable', e);
diff --git a/packages/base/links-to-editor.gts b/packages/base/links-to-editor.gts
index 867a85871b1..2c22b582412 100644
--- a/packages/base/links-to-editor.gts
+++ b/packages/base/links-to-editor.gts
@@ -28,11 +28,15 @@ import {
   Loader,
   type ResolvedCodeRef,
   isCardInstance,
+  cardTypeName,
 } from '@cardstack/runtime-common';
-import { Button, IconButton } from '@cardstack/boxel-ui/components';
+import {
+  BrokenLinkTemplate,
+  Button,
+  IconButton,
+} from '@cardstack/boxel-ui/components';
 import { IconMinusCircle } from '@cardstack/boxel-ui/icons';
 import { consume } from 'ember-provide-consume-context';
-import BrokenLinkTemplate from './default-templates/broken-link-template';
 import { type RelationshipState } from './field-support';
 
 // A broken singular link surfaces as a terminal failure state from
@@ -109,6 +113,7 @@ export class LinksToEditor extends GlimmerComponent<Signature> {
               @errorDoc={{@brokenLink.errorDoc}}
               @state={{@brokenLink.kind}}
               @format='embedded'
+              @displayName={{cardTypeName @brokenLink.reference}}
               @viewCard={{crud.viewCard}}
             />
           </CardCrudFunctionsConsumer>
diff --git a/packages/base/links-to-many-component.gts b/packages/base/links-to-many-component.gts
index bf45995b034..f14b770ee77 100644
--- a/packages/base/links-to-many-component.gts
+++ b/packages/base/links-to-many-component.gts
@@ -16,7 +16,6 @@ import {
   isFileDef,
   brokenLinkFormat,
 } from './card-api';
-import BrokenLinkTemplate from './default-templates/broken-link-template';
 import {
   getRelationshipMembershipState,
   type RelationshipState,
@@ -29,7 +28,12 @@ import {
   PermissionsConsumer,
   getBoxComponent,
 } from './field-component';
-import { Button, IconButton, Pill } from '@cardstack/boxel-ui/components';
+import {
+  BrokenLinkTemplate,
+  Button,
+  IconButton,
+  Pill,
+} from '@cardstack/boxel-ui/components';
 import { restartableTask } from 'ember-concurrency';
 import {
   chooseCard,
@@ -46,6 +50,7 @@ import {
   uuidv4,
   CardCrudFunctionsContextName,
   CardErrorJSONAPI,
+  cardTypeName,
 } from '@cardstack/runtime-common';
 import {
   IconMinusCircle,
@@ -303,6 +308,7 @@ class LinksToManyStandardEditor extends GlimmerComponent<LinksToManyStandardEdit
                     @errorDoc={{entry.broken.errorDoc}}
                     @state={{entry.broken.kind}}
                     @format='fitted'
+                    @displayName={{cardTypeName entry.broken.reference}}
                     @viewCard={{crud.viewCard}}
                     data-test-plural-view-item={{entry.index}}
                   />
@@ -458,6 +464,7 @@ class LinksToManyCompactEditor extends GlimmerComponent<LinksToManyCompactEditor
                     @errorDoc={{broken.errorDoc}}
                     @state={{broken.kind}}
                     @format='atom'
+                    @displayName={{cardTypeName broken.reference}}
                     @viewCard={{crud.viewCard}}
                     data-test-plural-view-item={{i}}
                   />
@@ -715,6 +722,7 @@ export function getLinksToManyComponent({
                               effectiveFormat
                               effectiveFormat
                             }}
+                            @displayName={{cardTypeName broken.reference}}
                             @viewCard={{crud.viewCard}}
                             data-test-plural-view-item={{i}}
                           />
diff --git a/packages/boxel-ui/addon/raw-icons/warning-triangle-filled.svg b/packages/boxel-ui/addon/raw-icons/warning-triangle-filled.svg
new file mode 100644
index 00000000000..f7f933bc29e
--- /dev/null
+++ b/packages/boxel-ui/addon/raw-icons/warning-triangle-filled.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path fill="#ffa515" stroke="#ffa515" stroke-width="1.5" stroke-linejoin="round" d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"/>
+  <path fill="none" stroke="#1a1a1a" stroke-width="2.2" stroke-linecap="round" d="M12 9.2v4.3"/>
+  <circle fill="#1a1a1a" cx="12" cy="16.9" r="1.05"/>
+</svg>
diff --git a/packages/boxel-ui/addon/src/components.ts b/packages/boxel-ui/addon/src/components.ts
index 75a1914ede4..4068568f948 100644
--- a/packages/boxel-ui/addon/src/components.ts
+++ b/packages/boxel-ui/addon/src/components.ts
@@ -3,6 +3,14 @@ import AddButton from './components/add-button/index.gts';
 import Alert from './components/alert/index.gts';
 import Avatar from './components/avatar/index.gts';
 import BasicFitted from './components/basic-fitted/index.gts';
+import BrokenLink, {
+  type BrokenLinkErrorDoc,
+  type BrokenLinkFormat,
+  type BrokenLinkItemType,
+  type BrokenLinkState,
+  type BrokenLinkTemplateArgs,
+  type BrokenLinkViewFn,
+} from './components/broken-link/index.gts';
 import Button from './components/button/index.gts';
 import BoxelButton from './components/button/index.gts';
 import CardContainer from './components/card-container/index.gts';
@@ -95,6 +103,12 @@ import ViewSelector, {
 } from './components/view-selector/index.gts';
 
 export {
+  type BrokenLinkErrorDoc,
+  type BrokenLinkFormat,
+  type BrokenLinkItemType,
+  type BrokenLinkState,
+  type BrokenLinkTemplateArgs,
+  type BrokenLinkViewFn,
   type Filter,
   type FittedCardLayout,
   type FittedCardTitleTag,
@@ -126,6 +140,7 @@ export {
   BoxelMultiSelectBasic,
   BoxelSelect,
   BoxelTag,
+  BrokenLink as BrokenLinkTemplate,
   Button,
   CardContainer,
   CardHeader,
diff --git a/packages/base/default-templates/broken-link-template.gts b/packages/boxel-ui/addon/src/components/broken-link/index.gts
similarity index 86%
rename from packages/base/default-templates/broken-link-template.gts
rename to packages/boxel-ui/addon/src/components/broken-link/index.gts
index bf27bcb0ae6..d712035b710 100644
--- a/packages/base/default-templates/broken-link-template.gts
+++ b/packages/boxel-ui/addon/src/components/broken-link/index.gts
@@ -1,37 +1,74 @@
-import GlimmerComponent from '@glimmer/component';
-import { tracked } from '@glimmer/tracking';
+import LinkOffIcon from '@cardstack/boxel-icons/link-off';
 import { on } from '@ember/modifier';
 import { guidFor } from '@ember/object/internals';
 import { htmlSafe } from '@ember/template';
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
 import { modifier } from 'ember-modifier';
-import LinkOffIcon from '@cardstack/boxel-icons/link-off';
-import { Button, CopyButton } from '@cardstack/boxel-ui/components';
-import { cardTypeName } from '@cardstack/runtime-common';
-import type { SerializedError } from '@cardstack/runtime-common';
-import type { ViewCardFn } from '../card-api';
+
+import WarningTriangleFilled from '../../icons/warning-triangle-filled.gts';
+import Button from '../button/index.gts';
+import ContextButton from '../context-button/index.gts';
+import CopyButton from '../copy-button/index.gts';
 
 type TipCorner = 'tl' | 'tr' | 'bl' | 'br';
 
 export type BrokenLinkState = 'error' | 'not-found';
 export type BrokenLinkFormat = 'isolated' | 'fitted' | 'embedded' | 'atom';
+// The kind of thing the broken reference points at. Card sites always pass
+// 'card'; the BFM chooser passes 'file' for `:file[...]` refs.
+export type BrokenLinkItemType = 'card' | 'file';
+
+// The failure payload the overlay reads. Kept local so boxel-ui carries no
+// dependency on runtime-common (which would invert the existing
+// runtime-common → boxel-ui edge into a cycle). It lists only the fields the
+// template renders; runtime-common's `SerializedError` is a structural
+// superset, so base callers can pass one unchanged.
+export interface BrokenLinkErrorDoc {
+  additionalErrors?: Array<{
+    message?: string;
+    stack?: string;
+    status?: number;
+    title?: string;
+  }> | null;
+  message?: string;
+  stack?: string;
+  status?: number;
+  title?: string;
+}
+
+// Navigates to the broken reference for "Open anyway". Local so boxel-ui needn't
+// import base's `ViewCardFn`; base's wider `crud.viewCard` (its first param
+// accepts `URL`) stays assignable to this.
+export type BrokenLinkViewFn = (url: URL) => void;
 
 export interface BrokenLinkTemplateArgs {
   brokenUrl: string;
-  errorDoc: SerializedError;
-  state: BrokenLinkState;
+  // Human-readable label shown next to the link-off icon. Card sites pass the
+  // card type name; the BFM file chooser passes the filename. Falls back to
+  // the capitalized `itemType` ('Card' / 'File') when omitted.
+  displayName?: string;
+  errorDoc: BrokenLinkErrorDoc;
   format: BrokenLinkFormat;
+  // The kind of reference, used for the reveal-overlay headline ("Linked card
+  // not found" vs "Linked file not found") and as the fallback label when no
+  // `displayName` is given. `linksTo` field sites are always cards; the BFM
+  // chooser passes 'file' for `:file[...]` refs. Falls back to 'card' when
+  // omitted.
+  itemType?: BrokenLinkItemType;
+  state: BrokenLinkState;
   // Threaded from the field component's CardCrudFunctions. When present, the
   // overlay offers an "Open anyway" affordance that navigates to the broken
   // reference (a stack visit in interact mode, a code-editor jump in code
   // mode — whatever the host's viewCard does for the current submode).
-  viewCard?: ViewCardFn;
+  viewCard?: BrokenLinkViewFn;
 }
 
 interface NormalizedAdditionalError {
   message: string;
+  stack?: string;
   status?: number;
   title?: string;
-  stack?: string;
 }
 
 // Only http(s) references are navigable. The brokenUrl is a card reference
@@ -50,62 +87,24 @@ function parseHttpUrl(url: string): URL | null {
   }
 }
 
-// Solid amber warning triangle with a black "!" — a two-tone svg the
-// single-colour boxel icon can't express. Shared by the reveal trigger and the
-// overlay title; `@size` sets both svg dimensions so each caller can match its
-// context.
-class WarningIcon extends GlimmerComponent<{
-  Element: SVGElement;
-  Args: { size: string };
-}> {
-  <template>
-    <svg
-      class='warn-icon'
-      viewBox='0 0 24 24'
-      width={{@size}}
-      height={{@size}}
-      aria-hidden='true'
-      ...attributes
-    >
-      <path
-        class='warn-icon-tri'
-        d='m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z'
-      />
-      <path class='warn-icon-mark' d='M12 9.2v4.3' />
-      <circle class='warn-icon-dot' cx='12' cy='16.9' r='1.05' />
-    </svg>
-    <style scoped>
-      .warn-icon {
-        display: block;
-      }
-      .warn-icon-tri {
-        fill: var(--boxel-warning-200, #ffba00);
-        stroke: var(--boxel-warning-200, #ffba00);
-        stroke-width: 1.5;
-        stroke-linejoin: round;
-      }
-      .warn-icon-mark {
-        fill: none;
-        stroke: #1a1a1a;
-        stroke-width: 2.2;
-        stroke-linecap: round;
-      }
-      .warn-icon-dot {
-        fill: #1a1a1a;
-      }
-    </style>
-  </template>
-}
-
 export default class BrokenLinkTemplate extends GlimmerComponent<{
-  Element: HTMLDivElement;
   Args: BrokenLinkTemplateArgs;
+  Element: HTMLDivElement;
 }> {
+  private get itemType(): BrokenLinkItemType {
+    return this.args.itemType ?? 'card';
+  }
+
   // The placeholder box is identical for every failure — what went wrong only
-  // surfaces inside the reveal overlay. `typeName` is the human-readable label
-  // shown next to the link-off icon, derived from the reference URL.
-  private get typeName(): string {
-    return cardTypeName(this.args.brokenUrl);
+  // surfaces inside the reveal overlay. `displayName` is the human-readable
+  // label shown next to the link-off icon; when the caller supplies none it
+  // falls back to the capitalized itemType ('Card' / 'File').
+  private get displayName(): string {
+    let { displayName } = this.args;
+    if (displayName) {
+      return displayName;
+    }
+    return this.itemType.charAt(0).toUpperCase() + this.itemType.slice(1);
   }
 
   private get isNotFound() {
@@ -114,8 +113,8 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
 
   private get headline() {
     return this.isNotFound
-      ? 'Linked card not found'
-      : 'Linked card failed to load';
+      ? `Linked ${this.itemType} not found`
+      : `Linked ${this.itemType} failed to load`;
   }
 
   private get statusLabel(): string {
@@ -181,9 +180,10 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
     return `${n} additional error${n === 1 ? '' : 's'}`;
   }
 
-  // The toggle checkbox and the trigger/close labels are wired by id; the
-  // overlay and tip anchor by dashed-ident. All must be unique per instance so
-  // multiple broken links on a page don't cross-trigger.
+  // The toggle checkbox and the trigger <label> are wired by id (the close
+  // button unchecks the toggle in JS instead); the overlay and tip anchor by
+  // dashed-ident. All must be unique per instance so multiple broken links on a
+  // page don't cross-trigger.
   private toggleId = `broken-link-reveal-${guidFor(this)}`;
   private anchorName = `--${this.toggleId}`;
   private overlayAnchorName = `--${this.toggleId}-ov`;
@@ -238,6 +238,20 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
   // and squares that corner.
   @tracked private tipCorner: TipCorner = 'br';
 
+  // The close control is a real button (ContextButton), not a <label>, so it
+  // can't toggle the reveal checkbox by `for=`. Uncheck it directly; the
+  // pure-CSS `:checked ~ .overlay` rule then hides the overlay. Unchecking
+  // programmatically fires no 'change' event, which is fine — onToggle only
+  // acts on the checked transition.
+  private close = () => {
+    let input = document.getElementById(
+      this.toggleId,
+    ) as HTMLInputElement | null;
+    if (input) {
+      input.checked = false;
+    }
+  };
+
   private onToggle = (event: Event) => {
     let input = event.target as HTMLInputElement;
     if (!input.checked) {
@@ -245,6 +259,11 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
     }
     let root = input.closest('.broken-link-template') as HTMLElement | null;
     if (root) {
+      // The overlay is revealed by pure CSS (`:checked ~ .overlay`), not an
+      // Ember render, so `afterRender` can't observe it. We genuinely need a
+      // post-paint callback to measure the laid-out overlay before picking the
+      // tip corner — the sanctioned use for rAF per the rule's own escape hatch.
+      // eslint-disable-next-line @cardstack/boxel/no-raf-for-state
       requestAnimationFrame(() => this.updateTipCorner(root));
     }
   };
@@ -347,7 +366,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
           <span
             class='type-name'
             data-test-broken-link-type
-          >{{this.typeName}}</span>
+          >{{this.displayName}}</span>
         </span>
         <label
           for={{this.toggleId}}
@@ -356,7 +375,12 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
           aria-label='Show broken link details'
           data-test-broken-link-reveal
         >
-          <WarningIcon @size='17' />
+          <WarningTriangleFilled
+            class='warn-icon'
+            width='17'
+            height='17'
+            aria-hidden='true'
+          />
         </label>
       </div>
 
@@ -373,15 +397,23 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
         <div class='overlay-header'>
           <div class='overlay-title-row'>
             <span class='overlay-title'>
-              <WarningIcon @size='16' />
+              <WarningTriangleFilled
+                class='warn-icon'
+                width='16'
+                height='16'
+                aria-hidden='true'
+              />
               <span data-test-broken-link-headline>{{this.headline}}</span>
             </span>
-            <label
-              for={{this.toggleId}}
+            <ContextButton
               class='overlay-close'
-              aria-label='Close'
+              @icon='close'
+              @label='Close'
+              @variant='ghost'
+              @size='extra-small'
+              {{on 'click' this.close}}
               data-test-broken-link-overlay-close
-            >×</label>
+            />
           </div>
           {{! The reference is informational only, never a clickable link. A
               copy affordance to its left puts the URL on the clipboard (same
@@ -549,7 +581,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
         min-height: inherit;
         border: 1px solid var(--boxel-border-color);
         border-radius: var(--boxel-border-radius);
-        background-color: var(--boxel-light-100);
+        background-color: var(--boxel-light-400);
         background-image:
           linear-gradient(
             to top right,
@@ -574,7 +606,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
            label's own padding is zeroed below so this gap is measured from the
            text edge, not the chip's padding box. */
         gap: 10px;
-        border-radius: var(--boxel-border-radius-sm);
+        border-radius: var(--boxel-border-radius-2xs);
       }
       .broken-link-template.atom .label {
         padding: 0;
@@ -585,8 +617,8 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
         align-items: center;
         gap: var(--boxel-sp-5xs);
         padding: var(--boxel-sp-5xs) var(--boxel-sp-4xs);
-        background-color: var(--boxel-light-100);
-        color: var(--boxel-500);
+        background-color: var(--boxel-light-400);
+        color: var(--boxel-dark);
         font: 500 var(--boxel-font-xs);
         line-height: 1.5;
         white-space: nowrap;
@@ -594,6 +626,10 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
       .label svg {
         flex: none;
       }
+      .warn-icon {
+        display: block;
+        flex: none;
+      }
       .type-name {
         overflow: hidden;
         text-overflow: ellipsis;
@@ -661,7 +697,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
            the trigger; the gap (defined on the root, shared with the tip)
            leaves the apex ~5px short of the trigger. */
         background-color: var(--boxel-light);
-        border: 1px solid var(--boxel-200);
+        border: 1px solid var(--boxel-border-color);
         border-radius: var(--boxel-border-radius);
         box-shadow: var(--boxel-deep-box-shadow);
         overflow: hidden;
@@ -695,21 +731,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
       }
       .overlay-close {
         flex: none;
-        display: inline-flex;
-        align-items: center;
-        justify-content: center;
-        width: 1.25rem;
-        height: 1.25rem;
         margin: -2px -2px 0 0;
-        border-radius: 50%;
-        color: var(--boxel-400);
-        font-size: 1.1rem;
-        line-height: 1;
-        cursor: pointer;
-      }
-      .overlay-close:hover {
-        background-color: var(--boxel-100);
-        color: var(--boxel-dark);
       }
       .overlay-url-row {
         display: flex;
@@ -758,8 +780,8 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
         margin-top: var(--boxel-sp-xs);
         padding: var(--boxel-sp-xs) var(--boxel-sp-sm);
         background-color: var(--boxel-light-100);
-        border: 1px solid var(--boxel-200);
-        border-radius: var(--boxel-form-control-border-radius);
+        border: 1px solid var(--boxel-border-color);
+        border-radius: var(--boxel-border-radius-2xs);
         font-size: 0.6875rem;
         font-weight: 700;
         letter-spacing: 0.04em;
@@ -773,13 +795,13 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
          white, separated by hairline dividers. */
       .diagnostics {
         margin-top: var(--boxel-sp-xs);
-        border: 1px solid var(--boxel-200);
-        border-radius: var(--boxel-form-control-border-radius);
+        border: 1px solid var(--boxel-border-color);
+        border-radius: var(--boxel-border-radius-2xs);
         overflow: hidden;
         background-color: var(--boxel-light);
       }
       .diag-section + .diag-section {
-        border-top: 1px solid var(--boxel-200);
+        border-top: 1px solid var(--boxel-border-color);
       }
       .diag-summary {
         display: flex;
@@ -822,7 +844,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
       }
       .diag-body {
         padding: var(--boxel-sp-sm);
-        border-top: 1px solid var(--boxel-200);
+        border-top: 1px solid var(--boxel-border-color);
         background-color: var(--boxel-light);
       }
       .error-message {
@@ -901,7 +923,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
         top: anchor(bottom);
         translate: 0 -1px;
         clip-path: polygon(0 0, 100% 0, 100% 100%);
-        border-right: 1px solid var(--boxel-200);
+        border-right: 1px solid var(--boxel-border-color);
       }
       .tip-br .overlay {
         right: anchor(center);
@@ -915,7 +937,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
         bottom: anchor(top);
         translate: 0 1px;
         clip-path: polygon(0 100%, 100% 0, 100% 100%);
-        border-right: 1px solid var(--boxel-200);
+        border-right: 1px solid var(--boxel-border-color);
       }
       .tip-tr .overlay {
         right: anchor(center);
@@ -929,7 +951,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
         top: anchor(bottom);
         translate: 0 -1px;
         clip-path: polygon(0 0, 100% 0, 0 100%);
-        border-left: 1px solid var(--boxel-200);
+        border-left: 1px solid var(--boxel-border-color);
       }
       .tip-bl .overlay {
         left: anchor(center);
@@ -943,7 +965,7 @@ export default class BrokenLinkTemplate extends GlimmerComponent<{
         bottom: anchor(top);
         translate: 0 1px;
         clip-path: polygon(0 0, 0 100%, 100% 100%);
-        border-left: 1px solid var(--boxel-200);
+        border-left: 1px solid var(--boxel-border-color);
       }
       .tip-tl .overlay {
         left: anchor(center);
diff --git a/packages/boxel-ui/addon/src/components/broken-link/usage.gts b/packages/boxel-ui/addon/src/components/broken-link/usage.gts
new file mode 100644
index 00000000000..770749a88c5
--- /dev/null
+++ b/packages/boxel-ui/addon/src/components/broken-link/usage.gts
@@ -0,0 +1,156 @@
+import { array, fn } from '@ember/helper';
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import FreestyleUsage from 'ember-freestyle/components/freestyle/usage';
+
+import BrokenLinkTemplate, {
+  type BrokenLinkErrorDoc,
+  type BrokenLinkFormat,
+  type BrokenLinkItemType,
+  type BrokenLinkState,
+} from './index.gts';
+
+export default class BrokenLinkUsage extends Component {
+  @tracked brokenUrl = 'https://example.com/realm/Author/exploded-card-id';
+  @tracked displayName = 'Author';
+  @tracked itemType: BrokenLinkItemType = 'card';
+  @tracked state: BrokenLinkState = 'not-found';
+  @tracked format: BrokenLinkFormat = 'embedded';
+
+  // errorDoc is an object arg; expose its rendered fields as individual
+  // controls and assemble them into the doc the overlay reads.
+  @tracked status = 404;
+  @tracked title = 'Not Found';
+  @tracked message = 'Could not find the linked card';
+  @tracked stack = '';
+
+  // Toggles the optional "Open anyway" affordance, which only shows when a
+  // viewCard handler is wired and the reference is a navigable http(s) URL.
+  @tracked enableViewCard = false;
+
+  private get errorDoc(): BrokenLinkErrorDoc {
+    return {
+      status: this.status,
+      title: this.title,
+      message: this.message,
+      stack: this.stack || undefined,
+      additionalErrors: null,
+    };
+  }
+
+  private viewCard = (url: URL) => {
+    alert(`Open anyway: ${url.href}`);
+  };
+
+  private get maybeViewCard() {
+    return this.enableViewCard ? this.viewCard : undefined;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='BrokenLinkTemplate'
+      @description='Placeholder shown when a card/file reference fails to resolve (deleted, moved, or no permission). Renders an identical box across failures — a link-off icon with the type/file label — and hides the diagnostics (status, message, stack, additional errors) behind a warning-triangle reveal overlay that also carries the reference URL and a copy button. Used by broken linksTo / linksToMany field values and the markdown-embed chooser.'
+    >
+      <:example>
+        <div class='broken-link-usage-frame'>
+          <BrokenLinkTemplate
+            @brokenUrl={{this.brokenUrl}}
+            @displayName={{this.displayName}}
+            @itemType={{this.itemType}}
+            @errorDoc={{this.errorDoc}}
+            @state={{this.state}}
+            @format={{this.format}}
+            @viewCard={{this.maybeViewCard}}
+          />
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='brokenUrl'
+          @description='The unresolvable reference. Shown (as plain text, never a link) in the reveal overlay with a copy button.'
+          @value={{this.brokenUrl}}
+          @onInput={{fn (mut this.brokenUrl)}}
+        />
+        <Args.String
+          @name='displayName'
+          @optional={{true}}
+          @description="Human-readable label next to the link-off icon — the card type name, or a filename for file refs. Falls back to the capitalized itemType ('Card' / 'File')."
+          @value={{this.displayName}}
+          @onInput={{fn (mut this.displayName)}}
+        />
+        <Args.String
+          @name='itemType'
+          @optional={{true}}
+          @description="The reference kind. Drives the overlay headline ('Linked card not found' vs 'Linked file not found') and the label fallback. Falls back to 'card'."
+          @options={{array 'card' 'file'}}
+          @value={{this.itemType}}
+          @onInput={{fn (mut this.itemType)}}
+        />
+        <Args.String
+          @name='state'
+          @description="'not-found' shows a single status badge; 'error' shows the diagnostics accordion. Also drives the overlay headline."
+          @options={{array 'not-found' 'error'}}
+          @value={{this.state}}
+          @onInput={{fn (mut this.state)}}
+        />
+        <Args.String
+          @name='format'
+          @description='Footprint of the placeholder box, mirroring the card format it stands in for.'
+          @options={{array 'atom' 'embedded' 'fitted' 'isolated'}}
+          @value={{this.format}}
+          @onInput={{fn (mut this.format)}}
+        />
+        <Args.Number
+          @name='errorDoc.status'
+          @description='HTTP-ish status code shown in the status badge / accordion header.'
+          @value={{this.status}}
+          @onInput={{fn (mut this.status)}}
+        />
+        <Args.String
+          @name='errorDoc.title'
+          @description='Status title shown alongside the code.'
+          @value={{this.title}}
+          @onInput={{fn (mut this.title)}}
+        />
+        <Args.String
+          @name='errorDoc.message'
+          @description='Error prose. Hidden for not-found (redundant with the URL) and when the stack already carries it.'
+          @value={{this.message}}
+          @onInput={{fn (mut this.message)}}
+        />
+        <Args.String
+          @name='errorDoc.stack'
+          @description='Optional stack trace shown in the error accordion body.'
+          @value={{this.stack}}
+          @onInput={{fn (mut this.stack)}}
+        />
+        <Args.Bool
+          @name='viewCard'
+          @description='Wire an "Open anyway" handler. The affordance shows only when set and the reference is a navigable http(s) URL.'
+          @value={{this.enableViewCard}}
+          @onInput={{fn (mut this.enableViewCard)}}
+          @defaultValue={{false}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      /* The placeholder fills its slot and lets the reveal overlay extend past
+         its footprint, bounded by the surrounding card. Give it a card-sized,
+         overflow-hidden frame so the demo mirrors a real card slot. */
+      .broken-link-usage-frame {
+        position: relative;
+        width: 100%;
+        max-width: 24rem;
+        min-height: 20rem;
+        margin: 0 auto;
+        padding: var(--boxel-sp);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        overflow: hidden;
+        background-color: var(--boxel-light);
+        border-radius: var(--boxel-border-radius);
+      }
+    </style>
+  </template>
+}
diff --git a/packages/boxel-ui/addon/src/icons.gts b/packages/boxel-ui/addon/src/icons.gts
index 7c86c31da58..5e5f897add8 100644
--- a/packages/boxel-ui/addon/src/icons.gts
+++ b/packages/boxel-ui/addon/src/icons.gts
@@ -82,6 +82,7 @@ import TriangleLeft from './icons/triangle-left.gts';
 import TriangleRight from './icons/triangle-right.gts';
 import Upload from './icons/upload.gts';
 import Warning from './icons/warning.gts';
+import WarningTriangleFilled from './icons/warning-triangle-filled.gts';
 
 export const ALL_ICON_COMPONENTS = [
   AiBw,
@@ -163,6 +164,7 @@ export const ALL_ICON_COMPONENTS = [
   TriangleRight,
   Upload,
   Warning,
+  WarningTriangleFilled,
 ];
 export {
   type Icon,
@@ -246,4 +248,5 @@ export {
   TriangleRight,
   Upload,
   Warning,
+  WarningTriangleFilled,
 };
diff --git a/packages/boxel-ui/addon/src/icons/warning-triangle-filled.gts b/packages/boxel-ui/addon/src/icons/warning-triangle-filled.gts
new file mode 100644
index 00000000000..3deb7918232
--- /dev/null
+++ b/packages/boxel-ui/addon/src/icons/warning-triangle-filled.gts
@@ -0,0 +1,30 @@
+// This file is auto-generated by 'pnpm rebuild:icons'
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+import type { Signature } from './types.ts';
+
+const IconComponent: TemplateOnlyComponent<Signature> = <template>
+  <svg
+    xmlns='http://www.w3.org/2000/svg'
+    width='24'
+    height='24'
+    viewBox='0 0 24 24'
+    ...attributes
+  ><path
+      fill='#ffa515'
+      stroke='#ffa515'
+      stroke-linejoin='round'
+      stroke-width='1.5'
+      d='m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z'
+    /><path
+      fill='none'
+      stroke='#1a1a1a'
+      stroke-linecap='round'
+      stroke-width='2.2'
+      d='M12 9.2v4.3'
+    /><circle cx='12' cy='16.9' r='1.05' fill='#1a1a1a' /></svg>
+</template>;
+
+// @ts-expect-error this is the only way to set a name on a Template Only Component currently
+IconComponent.name = 'WarningTriangleFilled';
+export default IconComponent;
diff --git a/packages/boxel-ui/addon/src/usage.ts b/packages/boxel-ui/addon/src/usage.ts
index 998b4e9935c..d14fbfe824d 100644
--- a/packages/boxel-ui/addon/src/usage.ts
+++ b/packages/boxel-ui/addon/src/usage.ts
@@ -6,6 +6,7 @@ import AddButtonUsage from './components/add-button/usage.gts';
 import AlertUsage from './components/alert/usage.gts';
 import AvatarUsage from './components/avatar/usage.gts';
 import BasicFittedUsage from './components/basic-fitted/usage.gts';
+import BrokenLinkUsage from './components/broken-link/usage.gts';
 import ButtonUsage from './components/button/usage.gts';
 import CardContainerUsage from './components/card-container/usage.gts';
 import CardHeaderUsage from './components/card-header/usage.gts';
@@ -63,6 +64,7 @@ export const ALL_USAGE_COMPONENTS = [
   ['Alert', AlertUsage],
   ['Avatar', AvatarUsage],
   ['BasicFitted', BasicFittedUsage],
+  ['BrokenLink', BrokenLinkUsage],
   ['Button', ButtonUsage],
   ['CardContainer', CardContainerUsage],
   ['CardHeader', CardHeaderUsage],
diff --git a/packages/boxel-ui/test-app/tests/integration/components/broken-link-test.gts b/packages/boxel-ui/test-app/tests/integration/components/broken-link-test.gts
new file mode 100644
index 00000000000..fc7388b692b
--- /dev/null
+++ b/packages/boxel-ui/test-app/tests/integration/components/broken-link-test.gts
@@ -0,0 +1,159 @@
+import { click, render } from '@ember/test-helpers';
+import { module, test } from 'qunit';
+import { setupRenderingTest } from 'test-app/tests/helpers';
+import {
+  BrokenLinkTemplate,
+  type BrokenLinkErrorDoc,
+} from '@cardstack/boxel-ui/components';
+
+const BROKEN_URL = 'https://example.com/realm/Author/exploded-card-id';
+
+const notFoundDoc: BrokenLinkErrorDoc = {
+  status: 404,
+  title: 'Not Found',
+  message: `Could not find ${BROKEN_URL}`,
+  additionalErrors: null,
+};
+
+const errorDoc: BrokenLinkErrorDoc = {
+  status: 500,
+  title: 'Internal Server Error',
+  message: 'TypeError: Cannot read properties of undefined (reading "name")',
+  stack: 'Error: kaboom\n    at Author.render (author.gts:42:7)',
+  additionalErrors: null,
+};
+
+module('Integration | Component | broken-link', function (hooks) {
+  setupRenderingTest(hooks);
+
+  test('renders the placeholder box with the caller-supplied type name', async function (assert) {
+    await render(
+      <template>
+        <BrokenLinkTemplate
+          @brokenUrl={{BROKEN_URL}}
+          @errorDoc={{notFoundDoc}}
+          @state='not-found'
+          @format='embedded'
+          @displayName='Author'
+        />
+      </template>,
+    );
+
+    assert.dom('[data-test-broken-link-template="embedded"]').exists();
+    assert.dom('[data-test-broken-link-state="not-found"]').exists();
+    assert.dom('[data-test-broken-link-type]').hasText('Author');
+    // The failure reason lives only in the (hidden) overlay.
+    assert.dom('[data-test-broken-link-url]').isNotVisible();
+  });
+
+  test('type name falls back to "Card" when none is supplied', async function (assert) {
+    await render(
+      <template>
+        <BrokenLinkTemplate
+          @brokenUrl={{BROKEN_URL}}
+          @errorDoc={{notFoundDoc}}
+          @state='not-found'
+          @format='embedded'
+        />
+      </template>,
+    );
+    assert.dom('[data-test-broken-link-type]').hasText('Card');
+  });
+
+  test('the reveal toggle opens the overlay with the URL and a copy button', async function (assert) {
+    await render(
+      <template>
+        <BrokenLinkTemplate
+          @brokenUrl={{BROKEN_URL}}
+          @errorDoc={{errorDoc}}
+          @state='error'
+          @format='isolated'
+          @displayName='Author'
+        />
+      </template>,
+    );
+
+    assert.dom('[data-test-broken-link-overlay]').isNotVisible();
+    await click('[data-test-broken-link-reveal]');
+    assert.dom('[data-test-broken-link-overlay]').isVisible();
+    assert.dom('[data-test-broken-link-url]').isVisible().hasText(BROKEN_URL);
+    assert.dom('[data-test-broken-link-copy]').exists();
+
+    await click('[data-test-broken-link-overlay-close]');
+    assert.dom('[data-test-broken-link-overlay]').isNotVisible();
+  });
+
+  test('the overlay headline distinguishes not-found from error', async function (assert) {
+    await render(
+      <template>
+        <BrokenLinkTemplate
+          @brokenUrl={{BROKEN_URL}}
+          @errorDoc={{notFoundDoc}}
+          @state='not-found'
+          @format='embedded'
+          @displayName='Author'
+        />
+      </template>,
+    );
+    assert
+      .dom('[data-test-broken-link-headline]')
+      .hasText('Linked card not found');
+
+    await render(
+      <template>
+        <BrokenLinkTemplate
+          @brokenUrl={{BROKEN_URL}}
+          @errorDoc={{errorDoc}}
+          @state='error'
+          @format='embedded'
+          @displayName='Author'
+        />
+      </template>,
+    );
+    assert
+      .dom('[data-test-broken-link-headline]')
+      .hasText('Linked card failed to load');
+    assert
+      .dom('[data-test-broken-link-status]')
+      .includesText('500')
+      .includesText('Internal Server Error');
+  });
+
+  test('the headline itemType defaults to "card" and honors an override', async function (assert) {
+    await render(
+      <template>
+        <BrokenLinkTemplate
+          @brokenUrl={{BROKEN_URL}}
+          @errorDoc={{notFoundDoc}}
+          @state='not-found'
+          @format='embedded'
+          @displayName='notes.md'
+          @itemType='file'
+        />
+      </template>,
+    );
+    assert
+      .dom('[data-test-broken-link-headline]')
+      .hasText(
+        'Linked file not found',
+        'the supplied itemType drives the headline',
+      );
+  });
+
+  test('the label falls back to the capitalized itemType when no displayName is given', async function (assert) {
+    await render(
+      <template>
+        <BrokenLinkTemplate
+          @brokenUrl={{BROKEN_URL}}
+          @errorDoc={{notFoundDoc}}
+          @state='not-found'
+          @format='embedded'
+          @itemType='file'
+        />
+      </template>,
+    );
+    assert
+      .dom('[data-test-broken-link-type]')
+      .hasText('File', 'the label capitalizes the itemType fallback');
+  });
+});
diff --git a/packages/host/app/components/markdown-embed-chooser/format-selection.ts b/packages/host/app/components/markdown-embed-chooser/format-selection.ts
index dcf4c8f9797..30f6ee766ac 100644
--- a/packages/host/app/components/markdown-embed-chooser/format-selection.ts
+++ b/packages/host/app/components/markdown-embed-chooser/format-selection.ts
@@ -155,7 +155,7 @@ export default class EmbedFormatSelection {
 
   // Frozen snapshot of the seeded state, captured once on construction from the
   // edit-mode preload. `isDirty` compares against it so the parent can flip the
-  // CTA between DONE and ACCEPT.
+  // CTA between Done and Accept.
   private initialSelectedValue: OptionValue;
   private initialKind: 'inline' | 'block';
   private initialWidthInput: string;
diff --git a/packages/host/app/components/markdown-embed-chooser/modal.gts b/packages/host/app/components/markdown-embed-chooser/modal.gts
index fe8e1825f6e..128ade94e21 100644
--- a/packages/host/app/components/markdown-embed-chooser/modal.gts
+++ b/packages/host/app/components/markdown-embed-chooser/modal.gts
@@ -65,6 +65,12 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
     return this.markdownEmbedChooser.currentRequest;
   }
 
+  // The editing document's own URL, threaded to both tabs so the chooser
+  // relativizes the picked ref against it (matching the format-picker path).
+  private get documentBaseUrl(): string | undefined {
+    return this.request?.documentBaseUrl;
+  }
+
   // Seeds for the shared format selection. `Tabs` owns the actual
   // `EmbedFormatSelection` instance — it lives inside the `{{#if this.request}}`
   // block, so it's created once per chooser invocation (seeded here from the
@@ -158,6 +164,7 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
                 @onInsert={{this.handleInsertCard}}
                 @selection={{selection}}
                 @initialTarget={{this.cardInitialTarget}}
+                @documentBaseUrl={{this.documentBaseUrl}}
                 @onRemove={{this.handleRemove}}
               />
             </:cards>
@@ -169,6 +176,7 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
                 @onInsert={{this.handleInsertFile}}
                 @selection={{selection}}
                 @initialTarget={{this.fileInitialTarget}}
+                @documentBaseUrl={{this.documentBaseUrl}}
                 @onRemove={{this.handleRemove}}
               />
             </:files>
diff --git a/packages/host/app/components/markdown-embed-chooser/pane.gts b/packages/host/app/components/markdown-embed-chooser/pane.gts
index b2f0232236e..e8b82fb4222 100644
--- a/packages/host/app/components/markdown-embed-chooser/pane.gts
+++ b/packages/host/app/components/markdown-embed-chooser/pane.gts
@@ -8,9 +8,15 @@ import {
   BoxelSelect,
   Button,
 } from '@cardstack/boxel-ui/components';
+import type {
+  BrokenLinkErrorDoc,
+  BrokenLinkItemType,
+  BrokenLinkState,
+} from '@cardstack/boxel-ui/components';
 import { IconX } from '@cardstack/boxel-ui/icons';
 
 import { serializeBfmRef } from '@cardstack/runtime-common/bfm-card-references';
+import { maybeRelativeReference } from '@cardstack/runtime-common/url';
 
 import PlacementToggle from './placement-toggle';
 
@@ -25,21 +31,33 @@ export { type OptionValue };
 interface Signature {
   Element: HTMLElement;
   Args: {
-    // Resolved instance being previewed. Its `id` is the BFM ref URL. Always a
-    // real target — the parent (tab-panel) only mounts the pane once a row is
-    // picked and its instance resolves, rendering its own placeholder until then.
-    target: CardDef | FileDef;
+    // Resolved instance being previewed. Its `id` is the BFM ref URL. Absent
+    // when the picked/preloaded ref failed to resolve — the broken-ref args
+    // below then drive the preview instead.
+    target?: CardDef | FileDef;
     // Which BFM keyword to emit: `:card[...]` vs `:file[...]`.
     refType: 'card' | 'file';
+    // Broken-ref state, set by the parent when the ref can't resolve. When
+    // `brokenUrl` is present (and `target` is not), the preview renders the
+    // broken-ref visual; the CTA still serializes `brokenUrl` so Done/Accept
+    // keep the ref.
+    brokenUrl?: string;
+    errorDoc?: BrokenLinkErrorDoc;
+    brokenState?: BrokenLinkState;
+    brokenDisplayName?: string;
+    brokenItemType?: BrokenLinkItemType;
     // The shared format/placement/size selection. Owned by the modal and shared
     // across both tabs so the choice survives a tab switch; this pane is a pure
     // view over it plus the resolved target.
     selection: EmbedFormatSelection;
+    // The editing document's own URL. The ref is relativized against it so the
+    // serialized directive is `../`-relative, matching the format-picker path.
+    documentBaseUrl?: string;
     // Receives the serialized BFM directive when the CTA is clicked. The host
     // owns actual cursor insertion.
     onInsert: (bfm: string) => void;
     // Overrides the dynamic "Insert as …" CTA label. Used in edit mode to
-    // show 'DONE' (clean) or 'ACCEPT' (dirty) per the design spec.
+    // show 'Done' (clean) or 'Accept' (dirty) per the design spec.
     ctaLabelOverride?: string;
   };
 }
@@ -58,11 +76,23 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
   }
 
   private get bfmString(): string {
-    let url = this.args.target.id;
+    let url = this.args.target?.id ?? this.args.brokenUrl;
     if (!url) {
       return '';
     }
-    return serializeBfmRef(this.args.refType, url, {
+    // Relativize against the editing document's URL so the inserted ref is
+    // `../`-relative — the same math the codemirror format-picker path uses.
+    // Falls back to the absolute URL when there's no base or it can't parse.
+    let ref = url;
+    let base = this.args.documentBaseUrl;
+    if (base) {
+      try {
+        ref = maybeRelativeReference(new URL(url), new URL(base), undefined);
+      } catch {
+        // Keep the absolute URL.
+      }
+    }
+    return serializeBfmRef(this.args.refType, ref, {
       kind: this.args.selection.kind,
       size: this.args.selection.sizeSpecifier,
     });
@@ -130,6 +160,11 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
       <div class='markdown-embed-preview-pane__viewport'>
         <MarkdownEmbedPreview
           @target={{@target}}
+          @brokenUrl={{@brokenUrl}}
+          @brokenDisplayName={{@brokenDisplayName}}
+          @brokenItemType={{@brokenItemType}}
+          @errorDoc={{@errorDoc}}
+          @brokenState={{@brokenState}}
           @format={{@selection.previewFormat}}
           @sizeSpec={{@selection.sizeSpec}}
           @kind={{@selection.kind}}
diff --git a/packages/host/app/components/markdown-embed-chooser/preview/index.gts b/packages/host/app/components/markdown-embed-chooser/preview/index.gts
index 9e33c11594f..07cf88bdd32 100644
--- a/packages/host/app/components/markdown-embed-chooser/preview/index.gts
+++ b/packages/host/app/components/markdown-embed-chooser/preview/index.gts
@@ -3,6 +3,12 @@ import { htmlSafe } from '@ember/template';
 
 import Component from '@glimmer/component';
 
+import { BrokenLinkTemplate } from '@cardstack/boxel-ui/components';
+import type {
+  BrokenLinkErrorDoc,
+  BrokenLinkItemType,
+  BrokenLinkState,
+} from '@cardstack/boxel-ui/components';
 import { eq, not } from '@cardstack/boxel-ui/helpers';
 
 import {
@@ -16,6 +22,11 @@ import type { CardDef, FileDef, Format } from '@cardstack/base/card-api';
 
 type EmbedFormat = 'atom' | 'embedded' | 'fitted' | 'isolated';
 
+// Stable identity for the "no error doc" fallback so the getter below doesn't
+// hand the broken template a fresh object every render (which would churn
+// downstream renders). The broken template only reads fields, never mutates.
+const EMPTY_ERROR_DOC: BrokenLinkErrorDoc = Object.freeze({});
+
 interface EmbedSignature {
   Element: HTMLElement;
   Args: {
@@ -101,14 +112,98 @@ const Embed: TOC<EmbedSignature> = <template>
   </style>
 </template>;
 
+interface BrokenEmbedSignature {
+  Element: HTMLElement;
+  Args: {
+    brokenUrl: string;
+    errorDoc: BrokenLinkErrorDoc;
+    state: BrokenLinkState;
+    displayName?: string;
+    itemType?: BrokenLinkItemType;
+    format: EmbedFormat;
+    kind: 'inline' | 'block';
+    sizeStyle?: ReturnType<typeof htmlSafe>;
+  };
+}
+
+// Placement wrapper for a broken ref, mirroring Embed's inline/block behavior so
+// a broken inline ref (`:card[url | embedded]`) previews inline — the same
+// placement it will serialize to — rather than collapsing to a block. Unlike
+// Embed it adds no card-frame and never sets `overflow: hidden`: the broken
+// template draws its own box, and its reveal overlay must stay free to extend
+// beyond the placeholder footprint. It carries no `data-test-markdown-embed-preview`
+// so the broken state stays distinguishable from a resolved embed.
+const BrokenEmbed: TOC<BrokenEmbedSignature> = <template>
+  {{#if (eq @kind 'inline')}}
+    <span
+      class='broken-embed
+        {{if
+          (eq @format "atom")
+          "broken-embed--inline"
+          "broken-embed--inline-embed"
+        }}'
+      ...attributes
+    >
+      <BrokenLinkTemplate
+        @brokenUrl={{@brokenUrl}}
+        @displayName={{@displayName}}
+        @itemType={{@itemType}}
+        @errorDoc={{@errorDoc}}
+        @state={{@state}}
+        @format={{@format}}
+        style={{@sizeStyle}}
+      />
+    </span>
+  {{else}}
+    <div class='broken-embed broken-embed--block' ...attributes>
+      <BrokenLinkTemplate
+        @brokenUrl={{@brokenUrl}}
+        @displayName={{@displayName}}
+        @itemType={{@itemType}}
+        @errorDoc={{@errorDoc}}
+        @state={{@state}}
+        @format={{@format}}
+        style={{@sizeStyle}}
+      />
+    </div>
+  {{/if}}
+  <style scoped>
+    .broken-embed {
+      max-width: 100%;
+    }
+    .broken-embed--inline {
+      display: inline-flex;
+      vertical-align: middle;
+    }
+    .broken-embed--inline-embed {
+      display: inline-block;
+      vertical-align: middle;
+    }
+    .broken-embed--block {
+      display: block;
+    }
+  </style>
+</template>;
+
 interface Signature {
   Element: HTMLElement;
   Args: {
     // Already-resolved instance to preview. Both card refs (`:card[...]`) and
     // file refs (`:file[...]`) render through the same CardRenderer, so the
     // caller resolves the URL and hands us the instance — this component loads
-    // nothing.
-    target: CardDef | FileDef;
+    // nothing. Absent when the ref failed to resolve; the broken-ref args
+    // below then drive the render.
+    target?: CardDef | FileDef;
+    // Broken-ref render: when `brokenUrl` is present (and `target` is not),
+    // render `BrokenLinkTemplate` instead of the embed. The same warning box +
+    // reveal overlay the base `linksTo` broken UI shows, format-aware so the
+    // format dropdown still drives its footprint. No `@viewCard` — the chooser
+    // offers no "Open anyway".
+    brokenUrl?: string;
+    errorDoc?: BrokenLinkErrorDoc;
+    brokenState?: BrokenLinkState;
+    brokenDisplayName?: string;
+    brokenItemType?: BrokenLinkItemType;
     // Render format. `fitted` consults `@sizeSpec` for its width/height;
     // atom/embedded/isolated ignore it.
     format: EmbedFormat;
@@ -140,6 +235,37 @@ export default class MarkdownEmbedPreview extends Component<Signature> {
     return this.args.format;
   }
 
+  // The broken template requires a state + error doc; default them so the arg
+  // types stay optional at this boundary (the parent only sets them alongside
+  // `brokenUrl`, but the correlation isn't expressible in the type).
+  private get brokenState(): BrokenLinkState {
+    return this.args.brokenState ?? 'error';
+  }
+
+  private get brokenErrorDoc(): BrokenLinkErrorDoc {
+    return this.args.errorDoc ?? EMPTY_ERROR_DOC;
+  }
+
+  // A fitted broken placeholder takes the same picked footprint as a real
+  // fitted embed, so the chooser previews the actual tile size rather than
+  // collapsing to the template's min-height. Unlike the embed's `sizeStyle`
+  // this omits `overflow: hidden`: the broken template's root must not clip, or
+  // the reveal overlay (which extends beyond the placeholder) would be cut off
+  // — the inner `.box` handles its own clipping. Non-fitted formats keep their
+  // intrinsic footprint.
+  private get brokenSizeStyle(): ReturnType<typeof htmlSafe> | undefined {
+    if (this.args.format !== 'fitted') {
+      return undefined;
+    }
+    let { width, height } = this.args.sizeSpec ?? { format: 'fitted' };
+    let { sizeStyle } = bfmRefFormatAndSize(
+      'fitted',
+      width === undefined ? undefined : String(width),
+      height === undefined ? undefined : String(height),
+    );
+    return sizeStyle ? htmlSafe(sizeStyle) : undefined;
+  }
+
   // Fitted slots carry an inline width/height plus `overflow: hidden` so the
   // instance occupies the requested footprint — derived through the same helper
   // the live markdown renderer uses (`rendered-markdown.gts`). Inline embedded
@@ -194,12 +320,25 @@ export default class MarkdownEmbedPreview extends Component<Signature> {
             class='markdown-embed-preview-doc__word is-sm'
             aria-hidden='true'
           ></span>
-          <Embed
-            @target={{@target}}
-            @format={{this.renderFormat}}
-            @kind={{this.kind}}
-            @sizeStyle={{this.sizeStyle}}
-          />
+          {{#if @target}}
+            <Embed
+              @target={{@target}}
+              @format={{this.renderFormat}}
+              @kind={{this.kind}}
+              @sizeStyle={{this.sizeStyle}}
+            />
+          {{else if @brokenUrl}}
+            <BrokenEmbed
+              @brokenUrl={{@brokenUrl}}
+              @displayName={{@brokenDisplayName}}
+              @itemType={{@brokenItemType}}
+              @errorDoc={{this.brokenErrorDoc}}
+              @state={{this.brokenState}}
+              @format={{@format}}
+              @kind={{this.kind}}
+              @sizeStyle={{this.brokenSizeStyle}}
+            />
+          {{/if}}
           <span
             class='markdown-embed-preview-doc__word is-lg'
             aria-hidden='true'
@@ -218,7 +357,7 @@ export default class MarkdownEmbedPreview extends Component<Signature> {
           aria-hidden='true'
         ></span>
       </div>
-    {{else}}
+    {{else if @target}}
       <Embed
         @target={{@target}}
         @format={{this.renderFormat}}
@@ -226,6 +365,18 @@ export default class MarkdownEmbedPreview extends Component<Signature> {
         @sizeStyle={{this.sizeStyle}}
         ...attributes
       />
+    {{else if @brokenUrl}}
+      <BrokenEmbed
+        @brokenUrl={{@brokenUrl}}
+        @displayName={{@brokenDisplayName}}
+        @itemType={{@brokenItemType}}
+        @errorDoc={{this.brokenErrorDoc}}
+        @state={{this.brokenState}}
+        @format={{@format}}
+        @kind={{this.kind}}
+        @sizeStyle={{this.brokenSizeStyle}}
+        ...attributes
+      />
     {{/if}}
     <style scoped>
       .markdown-embed-preview-doc {
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
index f3279ba7b79..b9655552684 100644
--- a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
@@ -8,11 +8,24 @@ import { tracked } from '@glimmer/tracking';
 import { restartableTask } from 'ember-concurrency';
 
 import { BoxelButton } from '@cardstack/boxel-ui/components';
+import type {
+  BrokenLinkErrorDoc,
+  BrokenLinkItemType,
+  BrokenLinkState,
+} from '@cardstack/boxel-ui/components';
 import { eq } from '@cardstack/boxel-ui/helpers';
 
-import { isCardErrorJSONAPI } from '@cardstack/runtime-common';
+import {
+  isCardErrorJSONAPI,
+  type CardErrorJSONAPI,
+} from '@cardstack/runtime-common';
+
+import {
+  cardTypeName,
+  fileNameFromUrl,
+} from '@cardstack/runtime-common/bfm-card-references';
 
-import { fileNameFromUrl } from '@cardstack/runtime-common/bfm-card-references';
+import { maybeRelativeReference } from '@cardstack/runtime-common/url';
 
 import MiniCardChooser from '@cardstack/host/components/card-chooser/mini';
 import MiniFileChooser from '@cardstack/host/components/file-chooser/mini';
@@ -49,6 +62,10 @@ interface Signature {
     // (The pane's format seed comes from the shared `@selection`, which the
     // modal seeds from this same target.)
     initialTarget?: MarkdownEmbedInitialTarget;
+    // The editing document's own URL. The label and the inserted ref are both
+    // relativized against it, so a fallback URL label reads as `../Type/id` —
+    // the same form the pane serializes into the directive.
+    documentBaseUrl?: string;
     // Fired when the user clicks "Remove" in `current` mode. The modal
     // resolves its deferred with `{ remove: true }`.
     onRemove?: () => void;
@@ -67,6 +84,11 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
 
   @tracked private selectedTarget: CardDef | FileDef | undefined;
   @tracked private selectedUrl: string | undefined;
+  // Set when the picked/preloaded ref fails to resolve (deleted, moved, no
+  // permission). Distinguishes "resolution failed" from "still loading /
+  // nothing picked" so the pane can render the broken-ref visual instead of
+  // the empty placeholder.
+  @tracked private selectedError: CardErrorJSONAPI | undefined;
   @tracked private mode: 'choose' | 'current' = 'choose';
 
   constructor(owner: Owner, args: Signature['Args']) {
@@ -97,22 +119,40 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
     return this.currentUrl !== initial;
   }
 
-  // 'DONE' until the user diverges from the initial preload, 'ACCEPT' once
+  // 'Done' until the user diverges from the initial preload, 'Accept' once
   // they do — matches Zeplin 08B. Non-edit (choose) tabs keep the dynamic
   // "Insert as …" label.
   private get ctaLabelOverride(): string | undefined {
     if (!this.isEditMode) return undefined;
     let dirty = this.args.selection.isDirty || this.targetChanged;
-    return dirty ? 'ACCEPT' : 'DONE';
+    return dirty ? 'Accept' : 'Done';
   }
 
   private get currentTargetLabel(): string {
     let t = this.selectedTarget;
-    if (!t) return this.selectedUrl ?? '';
+    if (!t) return this.toDisplayUrl(this.selectedUrl ?? '');
     if (this.args.refType === 'file') {
       return fileNameFromUrl(t.id ?? this.selectedUrl ?? '');
     }
-    return (t as CardDef).cardTitle ?? t.id ?? this.selectedUrl ?? '';
+    return (
+      (t as CardDef).cardTitle ??
+      this.toDisplayUrl(t.id ?? this.selectedUrl ?? '')
+    );
+  }
+
+  // When the label falls back to showing a raw URL (a broken ref, or a card
+  // with no title), relativize it against the editing document's own URL —
+  // yielding the `../Type/id` form the pane serializes into the directive, so
+  // the label matches what gets inserted. Falls back to the absolute URL when
+  // there's no base or either URL can't be parsed.
+  private toDisplayUrl(url: string): string {
+    let base = this.args.documentBaseUrl;
+    if (!url || !base) return url;
+    try {
+      return maybeRelativeReference(new URL(url), new URL(base), undefined);
+    } catch {
+      return url;
+    }
   }
 
   @action
@@ -133,18 +173,68 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
     async (url: string, refType: MarkdownEmbedRefType) => {
       this.selectedUrl = url;
       this.selectedTarget = undefined;
+      this.selectedError = undefined;
       let result =
         refType === 'card'
           ? await this.store.get(url)
           : await this.store.get<FileDef>(url, { type: 'file-meta' });
       if (isCardErrorJSONAPI(result)) {
-        this.selectedTarget = undefined;
+        // Keep `selectedUrl` and leave `selectedTarget` undefined; the pane
+        // renders the broken-ref visual from `selectedError` instead of the
+        // resolved embed.
+        this.selectedError = result;
         return;
       }
       this.selectedTarget = result as CardDef | FileDef;
     },
   );
 
+  // The pane mounts once a row is picked and either resolves (selectedTarget)
+  // or fails (selectedError); the empty placeholder shows only before then.
+  private get hasPreview(): boolean {
+    return !!this.selectedTarget || !!this.selectedError;
+  }
+
+  // Broken-ref state threaded to the pane. Each is undefined unless the load
+  // failed, so the pane renders the resolved embed on the happy path and the
+  // broken visual only when `selectedError` is set.
+  private get brokenUrl(): string | undefined {
+    return this.selectedError ? this.selectedUrl : undefined;
+  }
+
+  private get brokenState(): BrokenLinkState | undefined {
+    if (!this.selectedError) return undefined;
+    return this.selectedError.status === 404 ? 'not-found' : 'error';
+  }
+
+  private get brokenErrorDoc(): BrokenLinkErrorDoc | undefined {
+    let e = this.selectedError;
+    if (!e) return undefined;
+    return {
+      status: e.status,
+      title: e.title,
+      message: e.message,
+      stack: e.meta?.stack ?? undefined,
+      additionalErrors: e.additionalErrors ?? null,
+    };
+  }
+
+  // Card refs label by type name; file refs label by filename — matching the
+  // label the base `linksTo` broken visual derives for cards.
+  private get brokenDisplayName(): string | undefined {
+    if (!this.selectedError || !this.selectedUrl) return undefined;
+    return this.args.refType === 'file'
+      ? fileNameFromUrl(this.selectedUrl)
+      : cardTypeName(this.selectedUrl);
+  }
+
+  // Drives the broken-ref overlay headline ("Linked file not found" vs the
+  // card wording) so a broken `:file[...]` ref doesn't read as a card.
+  private get brokenItemType(): BrokenLinkItemType | undefined {
+    if (!this.selectedError) return undefined;
+    return this.args.refType === 'file' ? 'file' : 'card';
+  }
+
   @action
   private handleInsert(bfm: string) {
     let url = this.currentUrl;
@@ -225,13 +315,19 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
         {{/if}}
       </div>
       <div class='markdown-embed-chooser-tab-panel__right'>
-        {{#if this.selectedTarget}}
+        {{#if this.hasPreview}}
           <MarkdownEmbedPreviewPane
             @target={{this.selectedTarget}}
             @refType={{@refType}}
             @selection={{@selection}}
+            @documentBaseUrl={{@documentBaseUrl}}
             @onInsert={{this.handleInsert}}
             @ctaLabelOverride={{this.ctaLabelOverride}}
+            @brokenUrl={{this.brokenUrl}}
+            @brokenState={{this.brokenState}}
+            @brokenDisplayName={{this.brokenDisplayName}}
+            @brokenItemType={{this.brokenItemType}}
+            @errorDoc={{this.brokenErrorDoc}}
           />
         {{else}}
           <p
diff --git a/packages/host/app/services/markdown-embed-chooser.ts b/packages/host/app/services/markdown-embed-chooser.ts
index aad2b79449c..2dcfa677bb0 100644
--- a/packages/host/app/services/markdown-embed-chooser.ts
+++ b/packages/host/app/services/markdown-embed-chooser.ts
@@ -29,11 +29,17 @@ export interface MarkdownEmbedInitialTarget {
   // from `sizeSpec` so a size-less block directive (`::card[url]`) seeds block
   // placement instead of collapsing to an inline atom.
   kind?: 'inline' | 'block';
+  // The editing document's own URL. The chooser relativizes the picked ref
+  // against it so the inserted directive is `../`-relative, matching the
+  // format-picker insertion path.
+  documentBaseUrl?: string;
 }
 
 export interface MarkdownEmbedChooserRequest {
   defaultTab: MarkdownEmbedRefType;
   initialTarget?: MarkdownEmbedInitialTarget;
+  // The editing document's own URL, used to relativize the inserted ref.
+  documentBaseUrl?: string;
   deferred: Deferred<MarkdownEmbedResolution>;
 }
 
@@ -45,9 +51,12 @@ export default class MarkdownEmbedChooserService extends Service {
   @tracked currentRequest: MarkdownEmbedChooserRequest | undefined;
 
   chooseCardOrFile(
-    opts: { defaultTab?: MarkdownEmbedRefType } = {},
+    opts: { defaultTab?: MarkdownEmbedRefType; documentBaseUrl?: string } = {},
   ): Promise<MarkdownEmbedResolution> {
-    return this.open({ defaultTab: opts.defaultTab ?? 'card' });
+    return this.open({
+      defaultTab: opts.defaultTab ?? 'card',
+      documentBaseUrl: opts.documentBaseUrl,
+    });
   }
 
   editEmbed(
@@ -56,6 +65,7 @@ export default class MarkdownEmbedChooserService extends Service {
     return this.open({
       defaultTab: target.refType,
       initialTarget: target,
+      documentBaseUrl: target.documentBaseUrl,
     });
   }
 
@@ -68,6 +78,7 @@ export default class MarkdownEmbedChooserService extends Service {
   private async open(opts: {
     defaultTab: MarkdownEmbedRefType;
     initialTarget?: MarkdownEmbedInitialTarget;
+    documentBaseUrl?: string;
   }): Promise<MarkdownEmbedResolution> {
     if (this.currentRequest) {
       this.currentRequest.deferred.fulfill(undefined);
diff --git a/packages/host/tests/acceptance/markdown-embed-chooser-test.gts b/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
index f87a15f81c7..609d251546c 100644
--- a/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
+++ b/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
@@ -193,10 +193,13 @@ module('Acceptance | markdown embed chooser modal', function (hooks) {
     let docText = editorEl
       ? cmContext.EditorView.findFromDOM(editorEl)?.state.doc.toString()
       : undefined;
+    // The picked Pet lives in a sibling directory to the edited Note, so the
+    // inserted ref is relativized against the document — `../Pet/mango` — the
+    // same form the `/`-search format-picker path produces.
     assert.strictEqual(
       docText,
-      `:card[${mangoId}]`,
-      'source carries the inserted inline atom directive',
+      `:card[../Pet/mango]`,
+      'source carries the inserted inline atom directive, relativized to the document',
     );
   });
 
diff --git a/packages/host/tests/integration/components/broken-link-template-test.gts b/packages/host/tests/integration/components/broken-link-template-test.gts
index 30b14146ac5..9d94d64c84c 100644
--- a/packages/host/tests/integration/components/broken-link-template-test.gts
+++ b/packages/host/tests/integration/components/broken-link-template-test.gts
@@ -3,14 +3,11 @@ import { click, render } from '@ember/test-helpers';
 
 import { module, test } from 'qunit';
 
+import { BrokenLinkTemplate } from '@cardstack/boxel-ui/components';
+
 import type { SerializedError } from '@cardstack/runtime-common';
 
-// Relative import (not the `https://cardstack.com/base/…` realm URL): test
-// runner files are part of the host bundle, not loaded by the realm-loader,
-// so they need a real file-system path the bundler can resolve at build time.
-// @ts-ignore — bundler resolves this; TS lookup runs through the tsconfig
-// path map and the relative path is from .gts source.
-import BrokenLinkTemplate from '../../../../base/default-templates/broken-link-template';
+import { cardTypeName } from '@cardstack/runtime-common/bfm-card-references';
 
 import { setupRenderingTest } from '../../helpers/setup';
 
@@ -50,6 +47,9 @@ type Scenario = {
 };
 
 async function renderTemplate(scenario: Scenario) {
+  // The display-name label is now a caller-supplied prop; base card sites pass
+  // `cardTypeName(reference)`, so derive it the same way here.
+  let displayName = cardTypeName(scenario.brokenUrl);
   await render(
     <template>
       <BrokenLinkTemplate
@@ -57,6 +57,7 @@ async function renderTemplate(scenario: Scenario) {
         @errorDoc={{scenario.errorDoc}}
         @state={{scenario.state}}
         @format={{scenario.format}}
+        @displayName={{displayName}}
       />
     </template>,
   );
diff --git a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
index 157548d39c5..9117fda95b1 100644
--- a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
+++ b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
@@ -106,12 +106,15 @@ async function loadCodeMirrorEditor() {
 async function renderEditorAndModal(opts: {
   CodeMirrorEditor: any;
   harness: ContentHarness;
+  // The editing document's own URL. When set, document-relative refs in the
+  // body (`../books/mango`) resolve against it — matching the live editor.
+  cardReferenceBaseUrl?: string;
 }) {
   // Static `<template>` in this file can't reference a runtime-loaded
   // component, so build the layout with precompileTemplate and inject
   // CodeMirrorEditor through the scope. The modal is a regular host
   // component import so it can live alongside in static scope.
-  let { CodeMirrorEditor, harness } = opts;
+  let { CodeMirrorEditor, harness, cardReferenceBaseUrl } = opts;
   await render(
     precompileTemplate(
       `
@@ -121,6 +124,7 @@ async function renderEditorAndModal(opts: {
           <CodeMirrorEditor
             @content={{harness.content}}
             @onUpdate={{harness.set}}
+            @cardReferenceBaseUrl={{cardReferenceBaseUrl}}
           />
         </div>
       </HostContextProvider>
@@ -138,6 +142,7 @@ async function renderEditorAndModal(opts: {
           MarkdownEmbedChooserModal,
           CodeMirrorEditor,
           harness,
+          cardReferenceBaseUrl,
         }),
       },
     ),
@@ -493,4 +498,60 @@ module('Integration | codemirror embed toolbar', function (hooks) {
     svc.resolve(undefined);
     await settled();
   });
+
+  test('the pencil resolves a document-relative ref so the preview loads (not a blank pane)', async function (assert) {
+    // The body stores refs relative to the editing document; the chooser loads
+    // its preview through `store.get`, which needs the canonical absolute URL.
+    // A verbatim `../books/mango` would fail to resolve and the pane would show
+    // nothing — the pencil must resolve it against the document base first.
+    let docUrl = `${testRealmURL}experiments/playground`;
+    let harness = new ContentHarness();
+    harness.content = `:card[../books/mango]`;
+    await renderEditorAndModal({
+      CodeMirrorEditor,
+      harness,
+      cardReferenceBaseUrl: docUrl,
+    });
+
+    await waitFor('[data-test-codemirror-editor] .cm-content', {
+      timeout: 5000,
+    });
+    let editor = document.querySelector(
+      '[data-test-codemirror-editor] .cm-editor',
+    ) as HTMLElement | null;
+    let view = editor ? cmContext.EditorView.findFromDOM(editor) : null;
+    view?.focus();
+    // Drop the caret inside the relative URL (`:card[` is 6 chars).
+    view?.dispatch({ selection: { anchor: 8, head: 8 } });
+    await waitFor('[data-test-toolbar="edit-embed"]', { timeout: 5000 });
+
+    await click('[data-test-toolbar="edit-embed"]');
+    await waitFor('[data-test-markdown-embed-chooser-modal]', {
+      timeout: 5000,
+    });
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    assert.strictEqual(
+      svc.currentRequest?.initialTarget?.url,
+      mango,
+      'the relative ref resolves to its absolute URL before the chooser loads it',
+    );
+
+    // The resolved card actually renders its embed preview — the regression was
+    // a blank pane because the unresolved relative URL never loaded.
+    await waitFor(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview]',
+      { timeout: 5000 },
+    );
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview]',
+      )
+      .exists('the resolved card renders its preview in edit mode');
+
+    svc.resolve(undefined);
+    await settled();
+  });
 });
diff --git a/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts b/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
index f0f87cbc519..d723689ecc2 100644
--- a/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
+++ b/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
@@ -253,7 +253,124 @@ module('Integration | markdown-embed-chooser-modal', function (hooks) {
       .dom(
         '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview-cta]',
       )
-      .hasText('DONE', 'edit-mode CTA reads DONE while the form is clean');
+      .hasText('Done', 'edit-mode CTA reads Done while the form is clean');
+
+    // The preloaded card must actually render its embed in the preview — not
+    // just the CTA row.
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview]',
+      )
+      .exists('the preloaded card renders its embed preview in edit mode');
+
+    svc.resolve(undefined);
+    await pending;
+  });
+
+  test('edit-mode preload of a broken ref shows the broken preview + Remove/Replace, not the empty placeholder', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    // A card URL that isn't in the realm — the preload can't resolve it.
+    let brokenUrl = `${testRealmURL}books/ghost`;
+    // The editing document sits in a sibling directory, so the broken ref
+    // relativizes against it to a `../`-relative label.
+    let pending = svc.editEmbed({
+      refType: 'card',
+      url: brokenUrl,
+      sizeSpec: 'embedded',
+      documentBaseUrl: `${testRealmURL}posts/my-post`,
+    });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // The preview pane renders the broken-ref visual rather than the empty
+    // "search & preview" placeholder.
+    await waitFor(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-broken-link-template]',
+      { timeout: 5000 },
+    );
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-broken-link-template]',
+      )
+      .exists('the broken preview shows for an unresolvable preload');
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview-empty]',
+      )
+      .doesNotExist('the empty placeholder is suppressed for a broken ref');
+
+    // The current-target tile still offers Remove / Replace as the fix/remove
+    // affordance, and labels the broken ref by its URL.
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-chooser-current]',
+      )
+      .exists('the current-target tile renders for the broken preload');
+    // The label falls back to the ref (no title to show). It relativizes
+    // against the editing document's URL, so it reads as the `../`-relative
+    // path — the same form the pane serializes into the directive.
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-chooser-current-label]',
+      )
+      .hasText(
+        '../books/ghost',
+        'a broken ref labels as its document-relative path',
+      );
+    assert
+      .dom('[data-test-markdown-embed-chooser-remove]')
+      .exists('Remove is available');
+    assert
+      .dom('[data-test-markdown-embed-chooser-replace]')
+      .exists('Replace is available');
+
+    svc.resolve(undefined);
+    await pending;
+  });
+
+  test('a broken ref in a different realm than the document keeps its full URL as the label', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    // A broken ref in the base realm while the editing document lives in the
+    // test realm — the two are in different namespaces, so the ref can't be
+    // relativized and keeps its absolute URL.
+    let brokenUrl = `${baseRealm.url}ghost-card`;
+    let pending = svc.editEmbed({
+      refType: 'card',
+      url: brokenUrl,
+      sizeSpec: 'embedded',
+      documentBaseUrl: `${testRealmURL}posts/my-post`,
+    });
+    await waitFor(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-broken-link-template]',
+      { timeout: 5000 },
+    );
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-chooser-current-label]',
+      )
+      .hasText(
+        brokenUrl,
+        'a broken ref in another realm keeps its absolute URL',
+      );
 
     svc.resolve(undefined);
     await pending;
@@ -364,6 +481,53 @@ module('Integration | markdown-embed-chooser-modal', function (hooks) {
     );
   });
 
+  test('a picked card serializes a document-relative ref when a base URL is supplied', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    // The editing document lives in a sibling directory (`posts/`) to the
+    // picked card (`books/`), so the inserted ref collapses to `../books/mango`
+    // — matching the codemirror format-picker insertion path. The `url` in the
+    // result stays absolute (it's metadata; only the `bfm` ref is relativized).
+    let pending = svc.chooseCardOrFile({
+      defaultTab: 'card',
+      documentBaseUrl: `${testRealmURL}posts/my-post`,
+    });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    await fillIn(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-search-field]',
+      'Mango',
+    );
+    await waitFor(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mango}"]`,
+      { timeout: 5000 },
+    );
+    await click(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mango}"]`,
+    );
+
+    await waitFor('[data-test-markdown-embed-preview-cta]:not([disabled])', {
+      timeout: 5000,
+    });
+    await click('[data-test-markdown-embed-preview-cta]');
+
+    let result = await pending;
+    assert.deepEqual(
+      result,
+      { refType: 'card', url: mango, bfm: `:card[../books/mango]` },
+      'resolves with a document-relative BFM ref while keeping url absolute',
+    );
+  });
+
   test('the chosen format sticks when switching from the cards tab to the files tab', async function (assert) {
     await render(
       <template>
@@ -457,7 +621,7 @@ module('Integration | markdown-embed-chooser-modal', function (hooks) {
       .dom(
         '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview-cta]',
       )
-      .hasText('DONE', 'a clean edit keeps the DONE label');
+      .hasText('Done', 'a clean edit keeps the Done label');
 
     await click(
       '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview-cta]',
diff --git a/packages/host/tests/integration/components/markdown-embed-preview-pane-test.gts b/packages/host/tests/integration/components/markdown-embed-preview-pane-test.gts
index 01e671e67b9..bc5fe434d47 100644
--- a/packages/host/tests/integration/components/markdown-embed-preview-pane-test.gts
+++ b/packages/host/tests/integration/components/markdown-embed-preview-pane-test.gts
@@ -516,6 +516,46 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
     assert.strictEqual(harness.last, `::file[${card.id} | embedded]`);
   });
 
+  test('the inserted ref is relativized against the document base URL', async function (assert) {
+    let card = await loadCard();
+    let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
+    // The editing document lives in a sibling directory (`posts/`) to the
+    // picked card (`books/`), so the ref collapses to a `../`-relative form —
+    // the same shape the codemirror format-picker path produces.
+    let documentBaseUrl = `${testRealmURL}posts/my-post`;
+    await render(
+      <template>
+        <PaneBox>
+          <HostContextProvider>
+            <MarkdownEmbedPreviewPane
+              @target={{card}}
+              @refType='card'
+              @selection={{selection}}
+              @documentBaseUrl={{documentBaseUrl}}
+              @onInsert={{harness.onInsert}}
+            />
+          </HostContextProvider>
+        </PaneBox>
+      </template>,
+    );
+
+    await click('[data-test-markdown-embed-preview-cta]');
+    assert.strictEqual(
+      harness.last,
+      `:card[../books/mango]`,
+      'the inline atom ref is relativized against the document base URL',
+    );
+
+    await chooseFormat('embedded');
+    await click('[data-test-markdown-embed-preview-cta]');
+    assert.strictEqual(
+      harness.last,
+      `::card[../books/mango | embedded]`,
+      'the block directive carries the relative ref plus the format specifier',
+    );
+  });
+
   test('atom, embedded, isolated carry the has-divider modifier; fitted/custom do not', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
@@ -555,4 +595,45 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
         );
     }
   });
+
+  test('a broken ref surfaces the broken preview; the CTA still serializes the broken URL', async function (assert) {
+    let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
+    let brokenUrl = `${testRealmURL}books/deleted`;
+    let errorDoc = {
+      status: 404,
+      title: 'Not Found',
+      message: `Could not find ${brokenUrl}`,
+      additionalErrors: null,
+    };
+    await render(
+      <template>
+        <PaneBox>
+          <HostContextProvider>
+            <MarkdownEmbedPreviewPane
+              @refType='card'
+              @selection={{selection}}
+              @onInsert={{harness.onInsert}}
+              @brokenUrl={{brokenUrl}}
+              @brokenDisplayName='Book'
+              @errorDoc={{errorDoc}}
+              @brokenState='not-found'
+            />
+          </HostContextProvider>
+        </PaneBox>
+      </template>,
+    );
+
+    assert
+      .dom('[data-test-broken-link-template]')
+      .exists('the broken-ref visual surfaces in the pane');
+    assert.dom('[data-test-broken-link-type]').hasText('Book');
+
+    await click('[data-test-markdown-embed-preview-cta]');
+    assert.strictEqual(
+      harness.last,
+      `:card[${brokenUrl}]`,
+      'the CTA serializes the broken URL so Done/Accept keep the ref',
+    );
+  });
 });
diff --git a/packages/host/tests/integration/components/markdown-embed-preview-test.gts b/packages/host/tests/integration/components/markdown-embed-preview-test.gts
index d5457560d12..2fe7330c3a1 100644
--- a/packages/host/tests/integration/components/markdown-embed-preview-test.gts
+++ b/packages/host/tests/integration/components/markdown-embed-preview-test.gts
@@ -283,4 +283,179 @@ module('Integration | markdown-embed-preview', function (hooks) {
         'no skeleton document wrapper without @showSurroundingText',
       );
   });
+
+  test('renders the broken-ref visual (not the embed) for a 404 with the card type name', async function (assert) {
+    let brokenUrl = `${testRealmURL}Book/deleted`;
+    let errorDoc = {
+      status: 404,
+      title: 'Not Found',
+      message: `Could not find ${brokenUrl}`,
+      additionalErrors: null,
+    };
+    await render(
+      <template>
+        <PreviewBox>
+          <MarkdownEmbedPreview
+            @brokenUrl={{brokenUrl}}
+            @brokenDisplayName='Book'
+            @errorDoc={{errorDoc}}
+            @brokenState='not-found'
+            @format='embedded'
+          />
+        </PreviewBox>
+      </template>,
+    );
+    assert
+      .dom('[data-test-broken-link-template="embedded"]')
+      .exists('the broken-ref visual renders in place of the embed');
+    assert.dom('[data-test-broken-link-state="not-found"]').exists();
+    assert.dom('[data-test-broken-link-type]').hasText('Book');
+    assert.dom('[data-test-broken-link-url]').hasText(brokenUrl);
+    assert
+      .dom('[data-test-markdown-embed-preview]')
+      .doesNotExist('no resolved embed for a broken ref');
+  });
+
+  test('renders the broken-ref visual for a non-404 error state', async function (assert) {
+    let brokenUrl = `${testRealmURL}Book/exploded`;
+    let errorDoc = {
+      status: 500,
+      title: 'Internal Server Error',
+      message: 'TypeError: boom',
+      stack: 'Error: boom\n    at Book.render (book.gts:1:1)',
+      additionalErrors: null,
+    };
+    await render(
+      <template>
+        <PreviewBox>
+          <MarkdownEmbedPreview
+            @brokenUrl={{brokenUrl}}
+            @brokenDisplayName='Book'
+            @errorDoc={{errorDoc}}
+            @brokenState='error'
+            @format='fitted'
+          />
+        </PreviewBox>
+      </template>,
+    );
+    assert.dom('[data-test-broken-link-template="fitted"]').exists();
+    assert.dom('[data-test-broken-link-state="error"]').exists();
+    assert
+      .dom('[data-test-broken-link-headline]')
+      .hasText('Linked card failed to load');
+  });
+
+  test('a broken file ref is labelled by its filename and reads as a file, not a card', async function (assert) {
+    let brokenUrl = `${testRealmURL}files/notes.md`;
+    let errorDoc = {
+      status: 404,
+      title: 'Not Found',
+      message: `Could not find ${brokenUrl}`,
+      additionalErrors: null,
+    };
+    await render(
+      <template>
+        <PreviewBox>
+          <MarkdownEmbedPreview
+            @brokenUrl={{brokenUrl}}
+            @brokenDisplayName='notes.md'
+            @brokenItemType='file'
+            @errorDoc={{errorDoc}}
+            @brokenState='not-found'
+            @format='embedded'
+          />
+        </PreviewBox>
+      </template>,
+    );
+    assert.dom('[data-test-broken-link-type]').hasText('notes.md');
+    assert
+      .dom('[data-test-broken-link-headline]')
+      .hasText('Linked file not found', 'the overlay headline names a file');
+  });
+
+  test('a fitted broken ref takes the picked tile footprint and does not clip its overlay', async function (assert) {
+    let brokenUrl = `${testRealmURL}Book/deleted`;
+    let errorDoc = {
+      status: 404,
+      title: 'Not Found',
+      message: `Could not find ${brokenUrl}`,
+      additionalErrors: null,
+    };
+    // tall-tile = 150x275
+    let tallTile: BfmSizeSpec = { format: 'fitted', width: 150, height: 275 };
+    await render(
+      <template>
+        <PreviewBox>
+          <MarkdownEmbedPreview
+            @brokenUrl={{brokenUrl}}
+            @brokenDisplayName='Book'
+            @errorDoc={{errorDoc}}
+            @brokenState='not-found'
+            @format='fitted'
+            @sizeSpec={{tallTile}}
+          />
+        </PreviewBox>
+      </template>,
+    );
+    let style =
+      document
+        .querySelector('[data-test-broken-link-template="fitted"]')
+        ?.getAttribute('style') ?? '';
+    assert.ok(
+      style.includes('width: 150px'),
+      `fitted broken box takes the picked width (${style})`,
+    );
+    assert.ok(
+      style.includes('height: 275px'),
+      `fitted broken box takes the picked height (${style})`,
+    );
+    // The root must not clip, or the reveal overlay would be cut off — only the
+    // inner box clips its own content.
+    assert.notOk(
+      style.includes('overflow'),
+      'the broken root does not set overflow, so the reveal overlay is not clipped',
+    );
+  });
+
+  test('an inline broken ref previews inline, matching how it serializes (not as a block)', async function (assert) {
+    let brokenUrl = `${testRealmURL}Book/deleted`;
+    let errorDoc = {
+      status: 404,
+      title: 'Not Found',
+      message: `Could not find ${brokenUrl}`,
+      additionalErrors: null,
+    };
+    await render(
+      <template>
+        <PreviewBox>
+          <MarkdownEmbedPreview
+            @brokenUrl={{brokenUrl}}
+            @brokenDisplayName='Book'
+            @errorDoc={{errorDoc}}
+            @brokenState='not-found'
+            @format='embedded'
+            @kind='inline'
+          />
+        </PreviewBox>
+      </template>,
+    );
+    let wrapper = document.querySelector('.broken-embed');
+    assert.ok(wrapper, 'the broken ref is wrapped for placement');
+    assert.strictEqual(
+      wrapper?.tagName,
+      'SPAN',
+      'inline kind wraps the broken ref in a span (inline placement), not a block div',
+    );
+    // A non-atom inline ref takes the inline-block placement class — the same
+    // treatment a resolved inline embed gets — so it flows within text instead
+    // of collapsing to a block. (Computed display can't be asserted here: the
+    // PreviewBox flex parent blockifies its items.)
+    assert.ok(
+      wrapper?.classList.contains('broken-embed--inline-embed'),
+      'an inline embedded broken ref uses the inline-block placement class',
+    );
+    assert
+      .dom('.broken-embed [data-test-broken-link-template="embedded"]')
+      .exists('the broken template renders inside the inline wrapper');
+  });
 });
diff --git a/packages/host/tests/integration/realm-indexing-test.gts b/packages/host/tests/integration/realm-indexing-test.gts
index 56b5d51c33c..37bfa6946ff 100644
--- a/packages/host/tests/integration/realm-indexing-test.gts
+++ b/packages/host/tests/integration/realm-indexing-test.gts
@@ -4665,7 +4665,6 @@ module(`Integration | realm indexing`, function (hooks) {
         '@cardstack/base/card-serialization',
         '@cardstack/base/contains-many-component',
         '@cardstack/base/default-templates/atom',
-        '@cardstack/base/default-templates/broken-link-template',
         '@cardstack/base/default-templates/card-info',
         '@cardstack/base/default-templates/embedded',
         '@cardstack/base/default-templates/field-edit',
@@ -4834,7 +4833,6 @@ module(`Integration | realm indexing`, function (hooks) {
         '@cardstack/base/code-ref',
         '@cardstack/base/contains-many-component',
         '@cardstack/base/default-templates/atom',
-        '@cardstack/base/default-templates/broken-link-template',
         '@cardstack/base/default-templates/card-info',
         '@cardstack/base/default-templates/embedded',
         '@cardstack/base/default-templates/field-edit',
diff --git a/packages/runtime-common/bfm-card-references.ts b/packages/runtime-common/bfm-card-references.ts
index 3f950b70426..2e4efec7be3 100644
--- a/packages/runtime-common/bfm-card-references.ts
+++ b/packages/runtime-common/bfm-card-references.ts
@@ -375,11 +375,16 @@ export interface MarkdownEmbedInitialTarget {
   // from `sizeSpec` so a size-less block directive seeds block placement
   // instead of collapsing to an inline atom.
   kind?: 'inline' | 'block';
+  // The editing document's own URL. The chooser relativizes the picked ref
+  // against it so the inserted directive is `../`-relative, matching the
+  // format-picker insertion path.
+  documentBaseUrl?: string;
 }
 
 export interface MarkdownEmbedChooser {
   chooseCardOrFile(opts: {
     defaultTab?: 'card' | 'file';
+    documentBaseUrl?: string;
   }): Promise<MarkdownEmbedResolution>;
   editEmbed(
     target: MarkdownEmbedInitialTarget,
@@ -389,7 +394,7 @@ export interface MarkdownEmbedChooser {
 const MARKDOWN_EMBED_CHOOSER_KEY = '_CARDSTACK_MARKDOWN_EMBED_CHOOSER';
 
 export async function chooseMarkdownEmbed(
-  opts: { defaultTab?: 'card' | 'file' } = {},
+  opts: { defaultTab?: 'card' | 'file'; documentBaseUrl?: string } = {},
 ): Promise<MarkdownEmbedResolution> {
   let here = globalThis as any;
   let chooser: MarkdownEmbedChooser | undefined =