diff --git a/packages/base/codemirror-editor.gts b/packages/base/codemirror-editor.gts
index 813a9ecd3b9..f18bcff5f94 100644
--- a/packages/base/codemirror-editor.gts
+++ b/packages/base/codemirror-editor.gts
@@ -13,6 +13,11 @@ import {
   maybeRelativeReference,
   type VirtualNetwork,
 } from '@cardstack/runtime-common';
+import {
+  type BfmRefRange,
+  chooseMarkdownEmbed,
+  editMarkdownEmbed,
+} from '@cardstack/runtime-common/bfm-card-references';
 import {
   type BaseDef,
   type CardDef,
@@ -32,6 +37,8 @@ import ListIcon from '@cardstack/boxel-icons/list';
 import ListOrderedIcon from '@cardstack/boxel-icons/list-ordered';
 import BlockquoteIcon from '@cardstack/boxel-icons/blockquote';
 import LinkIcon from '@cardstack/boxel-icons/link';
+import PlusIcon from '@cardstack/boxel-icons/plus';
+import PencilIcon from '@cardstack/boxel-icons/pencil';
 
 // The CodeMirrorContext type is defined in the host app's lazy-loaded module.
 // We only use it as a type here — the actual module is loaded at runtime via
@@ -63,6 +70,9 @@ interface SelectionInfo {
   from: number;
   to: number;
   formats: SelectionFormats;
+  // BFM directive the cursor is currently inside, if any. Drives the toolbar
+  // swap between the Add-embed popover and the Edit-embed pencil.
+  currentRef?: BfmRefRange;
 }
 
 interface CodeMirrorContext {
@@ -193,7 +203,9 @@ function sameToolbarState(a: SelectionInfo, b: SelectionInfo): boolean {
     a.formats.italic === b.formats.italic &&
     a.formats.code === b.formats.code &&
     a.formats.strikethrough === b.formats.strikethrough &&
-    a.formats.link === b.formats.link
+    a.formats.link === b.formats.link &&
+    a.currentRef?.from === b.currentRef?.from &&
+    a.currentRef?.to === b.currentRef?.to
   );
 }
 
@@ -432,19 +444,84 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
     let f = this.toolbarFormats;
     let pressed = (active: boolean) => (active ? 'true' : 'false');
     return [
-      { testId: 'bold', label: 'Bold', icon: BoldIcon, action: this._wrapBold, active: f.bold, ariaPressed: pressed(f.bold) },
-      { testId: 'italic', label: 'Italic', icon: ItalicIcon, action: this._wrapItalic, active: f.italic, ariaPressed: pressed(f.italic) },
-      { testId: 'strikethrough', label: 'Strikethrough', icon: StrikethroughIcon, action: this._wrapStrikethrough, active: f.strikethrough, ariaPressed: pressed(f.strikethrough) },
-      { testId: 'code', label: 'Code', icon: CodeIcon, action: this._wrapCode, active: f.code, ariaPressed: pressed(f.code) },
-      { testId: 'link', label: 'Link', icon: LinkIcon, action: this._toggleLink, active: f.link, ariaPressed: pressed(f.link) },
+      {
+        testId: 'bold',
+        label: 'Bold',
+        icon: BoldIcon,
+        action: this._wrapBold,
+        active: f.bold,
+        ariaPressed: pressed(f.bold),
+      },
+      {
+        testId: 'italic',
+        label: 'Italic',
+        icon: ItalicIcon,
+        action: this._wrapItalic,
+        active: f.italic,
+        ariaPressed: pressed(f.italic),
+      },
+      {
+        testId: 'strikethrough',
+        label: 'Strikethrough',
+        icon: StrikethroughIcon,
+        action: this._wrapStrikethrough,
+        active: f.strikethrough,
+        ariaPressed: pressed(f.strikethrough),
+      },
+      {
+        testId: 'code',
+        label: 'Code',
+        icon: CodeIcon,
+        action: this._wrapCode,
+        active: f.code,
+        ariaPressed: pressed(f.code),
+      },
+      {
+        testId: 'link',
+        label: 'Link',
+        icon: LinkIcon,
+        action: this._toggleLink,
+        active: f.link,
+        ariaPressed: pressed(f.link),
+      },
       { divider: true },
-      { testId: 'h1', label: 'Heading 1', icon: Heading1Icon, action: this._insertH1 },
-      { testId: 'h2', label: 'Heading 2', icon: Heading2Icon, action: this._insertH2 },
-      { testId: 'h3', label: 'Heading 3', icon: Heading3Icon, action: this._insertH3 },
+      {
+        testId: 'h1',
+        label: 'Heading 1',
+        icon: Heading1Icon,
+        action: this._insertH1,
+      },
+      {
+        testId: 'h2',
+        label: 'Heading 2',
+        icon: Heading2Icon,
+        action: this._insertH2,
+      },
+      {
+        testId: 'h3',
+        label: 'Heading 3',
+        icon: Heading3Icon,
+        action: this._insertH3,
+      },
       { divider: true },
-      { testId: 'bullet-list', label: 'Bullet List', icon: ListIcon, action: this._toggleBulletList },
-      { testId: 'numbered-list', label: 'Numbered List', icon: ListOrderedIcon, action: this._toggleNumberedList },
-      { testId: 'blockquote', label: 'Blockquote', icon: BlockquoteIcon, action: this._toggleBlockquote },
+      {
+        testId: 'bullet-list',
+        label: 'Bullet List',
+        icon: ListIcon,
+        action: this._toggleBulletList,
+      },
+      {
+        testId: 'numbered-list',
+        label: 'Numbered List',
+        icon: ListOrderedIcon,
+        action: this._toggleNumberedList,
+      },
+      {
+        testId: 'blockquote',
+        label: 'Blockquote',
+        icon: BlockquoteIcon,
+        action: this._toggleBlockquote,
+      },
     ];
   }
 
@@ -565,6 +642,124 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
     view.focus();
   };
 
+  // ── Markdown embed chooser (toolbar) ────────────────────────────────────
+
+  @tracked _embedPopoverOpen = false;
+
+  get _currentBfmRef(): BfmRefRange | undefined {
+    return this._selectionInfo?.currentRef;
+  }
+
+  _toggleEmbedPopover = () => {
+    this._embedPopoverOpen = !this._embedPopoverOpen;
+  };
+
+  _openEmbedChooser = async (defaultTab: 'card' | 'file') => {
+    this._embedPopoverOpen = false;
+    let result;
+    try {
+      result = await chooseMarkdownEmbed({ defaultTab });
+    } 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.
+      console.warn('markdown-embed chooser unavailable', e);
+      return;
+    }
+    if (!result || 'remove' in result) {
+      // Cancelled, or { remove: true } returned by mistake (no current ref to
+      // remove in Add mode) — either way, do nothing.
+      return;
+    }
+    this._insertBfm(result.bfm);
+  };
+
+  _openEditEmbed = async () => {
+    let ref = this._currentBfmRef;
+    if (!ref) return;
+    let view = this.editorView;
+    if (!view) return;
+    let result;
+    try {
+      result = await editMarkdownEmbed({
+        refType: ref.refType as 'card' | 'file',
+        url: ref.url,
+        sizeSpec: ref.sizeSpec,
+      });
+    } catch (e) {
+      console.warn('markdown-embed chooser unavailable', e);
+      return;
+    }
+    if (!result) return;
+    if ('remove' in result) {
+      if (result.remove) {
+        this._deleteRange(ref);
+      }
+      return;
+    }
+    this._replaceRange(ref, result.bfm);
+  };
+
+  _insertBfm = (bfm: string) => {
+    let view = this.editorView;
+    if (!view) return;
+    let { from } = view.state.selection.main;
+
+    // Inline vs block placement is encoded in the directive's `::` prefix.
+    if (bfm.startsWith('::')) {
+      let line = view.state.doc.lineAt(from);
+      let insertPos = line.to;
+      let prefix = line.text.trim() === '' ? '' : '\n';
+      view.dispatch({
+        changes: { from: insertPos, insert: `${prefix}${bfm}\n` },
+      });
+    } else {
+      view.dispatch({ changes: { from, insert: bfm } });
+    }
+    view.focus();
+
+    let onUpdate = this.args.onUpdate;
+    if (onUpdate) {
+      if (this.saveTimer) {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = null;
+      }
+      onUpdate(view.state.doc.toString());
+    }
+  };
+
+  _replaceRange = (range: BfmRefRange, replacement: string) => {
+    let view = this.editorView;
+    if (!view) return;
+    view.dispatch({
+      changes: { from: range.from, to: range.to, insert: replacement },
+    });
+    view.focus();
+    let onUpdate = this.args.onUpdate;
+    if (onUpdate) {
+      onUpdate(view.state.doc.toString());
+    }
+  };
+
+  _deleteRange = (range: BfmRefRange) => {
+    let view = this.editorView;
+    if (!view) return;
+    // Block directives sit on their own line — extend the delete to swallow
+    // the surrounding newline so we don't leave a blank line behind.
+    let doc = view.state.doc;
+    let from = range.from;
+    let to = range.to;
+    if (range.kind === 'block') {
+      if (doc.sliceString(to, to + 1) === '\n') to += 1;
+      else if (from > 0 && doc.sliceString(from - 1, from) === '\n') from -= 1;
+    }
+    view.dispatch({ changes: { from, to, insert: '' } });
+    view.focus();
+    let onUpdate = this.args.onUpdate;
+    if (onUpdate) {
+      onUpdate(view.state.doc.toString());
+    }
+  };
+
   // ── Card insertion ───────────────────────────────────────────────────────
 
   _insertCardWithFormat = (format: string) => {
@@ -886,6 +1081,58 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
             <span class='toolbar-divider'></span>
           {{/if}}
 
+          {{#if this._currentBfmRef}}
+            <button
+              class='toolbar-btn'
+              data-test-toolbar='edit-embed'
+              type='button'
+              title='Edit embed'
+              aria-label='Edit embed'
+              {{on 'mousedown' this._preventFocusLoss}}
+              {{on 'click' this._openEditEmbed}}
+            ><PencilIcon width='16' height='16' /></button>
+          {{else}}
+            <div class='toolbar-embed-trigger'>
+              <button
+                class='toolbar-btn
+                  {{if this._embedPopoverOpen "toolbar-btn--active"}}'
+                data-test-toolbar='add-embed'
+                type='button'
+                title='Add embed'
+                aria-label='Add embed'
+                aria-haspopup='menu'
+                aria-expanded={{if this._embedPopoverOpen 'true' 'false'}}
+                {{on 'mousedown' this._preventFocusLoss}}
+                {{on 'click' this._toggleEmbedPopover}}
+              ><PlusIcon width='16' height='16' /></button>
+              {{#if this._embedPopoverOpen}}
+                <div
+                  class='toolbar-embed-popover'
+                  role='menu'
+                  data-test-toolbar-embed-popover
+                >
+                  <button
+                    type='button'
+                    role='menuitem'
+                    class='toolbar-embed-popover__item'
+                    data-test-toolbar-embed='card'
+                    {{on 'mousedown' this._preventFocusLoss}}
+                    {{on 'click' (fn this._openEmbedChooser 'card')}}
+                  >Add a card</button>
+                  <button
+                    type='button'
+                    role='menuitem'
+                    class='toolbar-embed-popover__item'
+                    data-test-toolbar-embed='file'
+                    {{on 'mousedown' this._preventFocusLoss}}
+                    {{on 'click' (fn this._openEmbedChooser 'file')}}
+                  >Add a file</button>
+                </div>
+              {{/if}}
+            </div>
+          {{/if}}
+          <span class='toolbar-divider'></span>
+
           {{#each this.toolbarButtons as |btn|}}
             {{#if btn.divider}}
               <span class='toolbar-divider'></span>
@@ -917,89 +1164,89 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
         ></div>
 
         {{! ── Card search popup ── }}
-      {{! template-lint-disable no-pointer-down-event-binding }}
-      {{#if this._cardSearchMode}}
-        <div
-          class='codemirror-card-search'
-          style={{this.menuStyle}}
-          data-test-card-search
-        >
-          <input
-            class='codemirror-card-search-input'
-            placeholder='Search cards or paste URL…'
-            aria-label='Search cards or paste URL'
-            value={{this._cardSearchText}}
-            data-codemirror-card-search-input
-            data-test-card-search-input
-            {{on 'input' this._handleCardSearchInput}}
-            {{on 'keydown' this._handleCardSearchKeydown}}
-          />
-          {{#if this.isSearchLoading}}
-            <div class='codemirror-card-search-loading'>Searching…</div>
-          {{/if}}
-          {{#if this.cardSearchResults.length}}
-            <div
-              class='codemirror-card-search-results'
-              data-test-card-search-results
-            >
-              {{#each this.cardSearchResults as |card index|}}
-                <button
-                  class='codemirror-card-search-result
-                    {{if (eq index this._cardSearchIndex) "selected"}}'
-                  data-test-card-search-result
-                  {{on 'mousedown' this._preventFocusLoss}}
-                  {{on 'click' (fn this._selectCardResult card)}}
-                >
-                  <span class='search-result-title'>{{card.title}}</span>
-                  {{#if card.id}}
-                    <span class='search-result-url'>{{card.id}}</span>
-                  {{/if}}
-                </button>
-              {{/each}}
-            </div>
-          {{/if}}
-        </div>
-      {{/if}}
+        {{! template-lint-disable no-pointer-down-event-binding }}
+        {{#if this._cardSearchMode}}
+          <div
+            class='codemirror-card-search'
+            style={{this.menuStyle}}
+            data-test-card-search
+          >
+            <input
+              class='codemirror-card-search-input'
+              placeholder='Search cards or paste URL…'
+              aria-label='Search cards or paste URL'
+              value={{this._cardSearchText}}
+              data-codemirror-card-search-input
+              data-test-card-search-input
+              {{on 'input' this._handleCardSearchInput}}
+              {{on 'keydown' this._handleCardSearchKeydown}}
+            />
+            {{#if this.isSearchLoading}}
+              <div class='codemirror-card-search-loading'>Searching…</div>
+            {{/if}}
+            {{#if this.cardSearchResults.length}}
+              <div
+                class='codemirror-card-search-results'
+                data-test-card-search-results
+              >
+                {{#each this.cardSearchResults as |card index|}}
+                  <button
+                    class='codemirror-card-search-result
+                      {{if (eq index this._cardSearchIndex) "selected"}}'
+                    data-test-card-search-result
+                    {{on 'mousedown' this._preventFocusLoss}}
+                    {{on 'click' (fn this._selectCardResult card)}}
+                  >
+                    <span class='search-result-title'>{{card.title}}</span>
+                    {{#if card.id}}
+                      <span class='search-result-url'>{{card.id}}</span>
+                    {{/if}}
+                  </button>
+                {{/each}}
+              </div>
+            {{/if}}
+          </div>
+        {{/if}}
 
-      {{! ── Format picker popup ── }}
-      {{! template-lint-disable no-pointer-down-event-binding }}
-      {{#if this._formatPickerCardUrl}}
-        <div
-          class='codemirror-format-picker'
-          style={{this.menuStyle}}
-          data-test-format-picker
-        >
-          <span class='format-picker-label'>
-            Insert "{{this._formatPickerCardTitle}}" as:
-          </span>
-          <div class='format-picker-buttons'>
-            <button
-              class='format-picker-btn'
-              data-test-format-inline
-              {{on 'mousedown' this._preventFocusLoss}}
-              {{on 'click' (fn this._insertCardWithFormat 'inline')}}
-            >
-              Inline
-            </button>
+        {{! ── Format picker popup ── }}
+        {{! template-lint-disable no-pointer-down-event-binding }}
+        {{#if this._formatPickerCardUrl}}
+          <div
+            class='codemirror-format-picker'
+            style={{this.menuStyle}}
+            data-test-format-picker
+          >
+            <span class='format-picker-label'>
+              Insert "{{this._formatPickerCardTitle}}" as:
+            </span>
+            <div class='format-picker-buttons'>
+              <button
+                class='format-picker-btn'
+                data-test-format-inline
+                {{on 'mousedown' this._preventFocusLoss}}
+                {{on 'click' (fn this._insertCardWithFormat 'inline')}}
+              >
+                Inline
+              </button>
+              <button
+                class='format-picker-btn format-picker-btn--primary'
+                data-test-format-block
+                {{on 'mousedown' this._preventFocusLoss}}
+                {{on 'click' (fn this._insertCardWithFormat 'block')}}
+              >
+                Block
+              </button>
+            </div>
             <button
-              class='format-picker-btn format-picker-btn--primary'
-              data-test-format-block
+              class='format-picker-dismiss'
+              data-test-format-picker-dismiss
               {{on 'mousedown' this._preventFocusLoss}}
-              {{on 'click' (fn this._insertCardWithFormat 'block')}}
+              {{on 'click' this._dismissFormatPicker}}
             >
-              Block
+              Cancel
             </button>
           </div>
-          <button
-            class='format-picker-dismiss'
-            data-test-format-picker-dismiss
-            {{on 'mousedown' this._preventFocusLoss}}
-            {{on 'click' this._dismissFormatPicker}}
-          >
-            Cancel
-          </button>
-        </div>
-      {{/if}}
+        {{/if}}
       </div>
 
       {{#if this.livePreview}}
@@ -1389,6 +1636,39 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
           margin: 0 var(--boxel-sp-5xs);
         }
 
+        .toolbar-embed-trigger {
+          position: relative;
+          display: inline-flex;
+        }
+        .toolbar-embed-popover {
+          position: absolute;
+          top: 100%;
+          left: 0;
+          margin-top: 4px;
+          min-width: 140px;
+          background: var(--boxel-light);
+          color: var(--boxel-dark);
+          border: 1px solid var(--boxel-300);
+          border-radius: var(--boxel-border-radius);
+          box-shadow: var(--boxel-deep-box-shadow);
+          padding: var(--boxel-sp-4xs) 0;
+          z-index: 5;
+          display: flex;
+          flex-direction: column;
+        }
+        .toolbar-embed-popover__item {
+          appearance: none;
+          background: none;
+          border: none;
+          text-align: left;
+          padding: var(--boxel-sp-4xs) var(--boxel-sp-xs);
+          font: var(--boxel-font-sm);
+          cursor: pointer;
+        }
+        .toolbar-embed-popover__item:hover {
+          background: var(--boxel-100);
+        }
+
         .codemirror-editor-loading {
           min-height: 120px;
           display: flex;
diff --git a/packages/host/app/components/card-chooser/mini/index.gts b/packages/host/app/components/card-chooser/mini/index.gts
index f40aae5e957..6dc24bd350e 100644
--- a/packages/host/app/components/card-chooser/mini/index.gts
+++ b/packages/host/app/components/card-chooser/mini/index.gts
@@ -82,10 +82,15 @@ export default class MiniCardChooser extends Component<Signature> {
         height: 100%;
         min-height: 0;
         background-color: var(--boxel-light);
+        /* Share the file chooser's compact scale so the two lists match when
+           toggling tabs in the markdown embed chooser. */
+        font: var(--boxel-font-sm);
       }
       .mini-card-chooser__header {
         flex: 0 0 auto;
-        padding: var(--boxel-sp-xs) var(--boxel-sp-xs) 0;
+        /* Small bottom inset so the search bar's 2px focus outline isn't
+           painted over by the results list sitting directly below it. */
+        padding: var(--boxel-sp-xs) var(--boxel-sp-xs) var(--boxel-sp-4xs);
       }
       /* Pill-shaped, design-matched bar height. SearchBar's defaults are
          tuned for the full search-sheet (50px tall, generous focus ring);
diff --git a/packages/host/app/components/card-search/panel-content.gts b/packages/host/app/components/card-search/panel-content.gts
index d0b05585b37..469e423a380 100644
--- a/packages/host/app/components/card-search/panel-content.gts
+++ b/packages/host/app/components/card-search/panel-content.gts
@@ -461,6 +461,11 @@ export default class PanelContent extends Component<Signature> {
       .search-sheet-content.mini :deep(.search-result-header) {
         padding-block: var(--boxel-sp-xs);
       }
+      /* The summary is 16px bold in the full sheet; in the mini envelope drop
+         it to the chooser's shared 14px scale (weight stays 600). */
+      .search-sheet-content.mini :deep(.search-result-header .summary) {
+        font: 600 var(--boxel-font-sm);
+      }
       /* Summary + Sort sit on one row, with the Sort dropdown shrunk to
          fit its label rather than padded to a comfortable touch target. */
       .search-sheet-content.mini :deep(.search-result-header .controls) {
diff --git a/packages/host/app/components/card-search/sheet-results.gts b/packages/host/app/components/card-search/sheet-results.gts
index 2514ae2afb9..a2224133e6b 100644
--- a/packages/host/app/components/card-search/sheet-results.gts
+++ b/packages/host/app/components/card-search/sheet-results.gts
@@ -205,6 +205,20 @@ export default class SheetResults extends Component<Signature> {
     return [...new Set(urls)];
   }
 
+  // The global summary + Sort row. Hidden in the mini chooser's default
+  // Recents view (empty search): there the Recents section supplies its own
+  // header (label + count), and the design shows no Sort control until the
+  // user actually searches. Unaffected for the full search sheet.
+  private get showGlobalHeader(): boolean {
+    if (!this.args.showHeader || this.args.isCompact) {
+      return false;
+    }
+    if (this.args.variant === 'mini' && this.args.isSearchKeyEmpty) {
+      return false;
+    }
+    return true;
+  }
+
   private get hasNoResults(): boolean {
     return (
       this.sections.length === 0 &&
@@ -230,24 +244,22 @@ export default class SheetResults extends Component<Signature> {
   }
 
   <template>
-    {{#if @showHeader}}
-      {{#unless @isCompact}}
-        <SearchResultHeader
-          @summaryText={{this.summaryText}}
-          @viewOptions={{this.VIEW_OPTIONS}}
-          @activeViewId={{@activeViewId}}
-          @activeSort={{@activeSort}}
-          @sortOptions={{this.SORT_OPTIONS}}
-          @onChangeView={{@onChangeView}}
-          @onChangeSort={{@onChangeSort}}
-          @multiSelect={{@multiSelect}}
-          @selectedCards={{@selectedCards}}
-          @allCards={{this.allCards}}
-          @onSelectAll={{@onSelectAll}}
-          @onDeselectAll={{@onDeselectAll}}
-          @hideViewSelector={{eq @variant 'mini'}}
-        />
-      {{/unless}}
+    {{#if this.showGlobalHeader}}
+      <SearchResultHeader
+        @summaryText={{this.summaryText}}
+        @viewOptions={{this.VIEW_OPTIONS}}
+        @activeViewId={{@activeViewId}}
+        @activeSort={{@activeSort}}
+        @sortOptions={{this.SORT_OPTIONS}}
+        @onChangeView={{@onChangeView}}
+        @onChangeSort={{@onChangeSort}}
+        @multiSelect={{@multiSelect}}
+        @selectedCards={{@selectedCards}}
+        @allCards={{this.allCards}}
+        @onSelectAll={{@onSelectAll}}
+        @onDeselectAll={{@onDeselectAll}}
+        @hideViewSelector={{eq @variant 'mini'}}
+      />
     {{/if}}
 
     {{! Handle empty URL search state — only after loading completes }}
diff --git a/packages/host/app/components/file-chooser/mini/index.gts b/packages/host/app/components/file-chooser/mini/index.gts
index 11160c059ce..29b7a041763 100644
--- a/packages/host/app/components/file-chooser/mini/index.gts
+++ b/packages/host/app/components/file-chooser/mini/index.gts
@@ -16,10 +16,15 @@ import FileChooser, { type FileChooserRealm } from '../panel';
 interface Signature {
   Element: HTMLDivElement;
   Args: {
-    // Fired with the absolute URL of the file the user picks from the tree or
-    // finishes uploading. The hosting container decides what to do with it
-    // (this primitive never confirms or dismisses on its own).
+    // Fired with the absolute URL of the file the user confirms (Enter on a
+    // tree row) or finishes uploading. The hosting container decides what to do
+    // with it (this primitive never confirms or dismisses on its own).
     onSelect: (url: string) => void;
+    // Fired on a single-click highlight of a tree row, before confirmation.
+    // Lets a host preview the highlighted file without committing to it — the
+    // card chooser previews on a single click, so this keeps the file chooser
+    // symmetric for consumers that want the same.
+    onHighlight?: (url: string) => void;
     // Workspace to open on first render. Read once at mount; later parent
     // updates are ignored. Defaults to the first known realm.
     initialRealmURL?: string;
@@ -72,8 +77,11 @@ export default class MiniFileChooser extends Component<Signature> {
       return;
     }
     this.userSelectedFile = path;
-    // Deliberately does NOT call this.args.onSelect — that only happens on
-    // confirmation (Enter) to avoid double-fire.
+    // Single click highlights the row and previews it via onHighlight, but does
+    // NOT call onSelect — that's reserved for confirmation (Enter) so a host
+    // can distinguish "previewing" from "committing".
+    let url = new RealmPaths(realm.url).fileURL(path);
+    this.args.onHighlight?.(url.href);
   }
 
   @action
@@ -211,7 +219,7 @@ export default class MiniFileChooser extends Component<Signature> {
         padding: var(--boxel-sp-xs);
         background-color: var(--boxel-light);
         color: var(--boxel-dark);
-        font: var(--boxel-font-xs);
+        font: var(--boxel-font-sm);
       }
       .mini-file-chooser__field {
         display: flex;
diff --git a/packages/host/app/components/markdown-embed-chooser/modal.gts b/packages/host/app/components/markdown-embed-chooser/modal.gts
new file mode 100644
index 00000000000..57e219c6fa0
--- /dev/null
+++ b/packages/host/app/components/markdown-embed-chooser/modal.gts
@@ -0,0 +1,192 @@
+import { registerDestructor } from '@ember/destroyable';
+import { hash } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { action } from '@ember/object';
+import type Owner from '@ember/owner';
+import { service } from '@ember/service';
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import focusTrap from 'ember-focus-trap/modifiers/focus-trap';
+
+import ModalContainer from '@cardstack/host/components/modal-container';
+
+import type MarkdownEmbedChooserService from '@cardstack/host/services/markdown-embed-chooser';
+import type {
+  MarkdownEmbedChooserRequest,
+  MarkdownEmbedRefType,
+} from '@cardstack/host/services/markdown-embed-chooser';
+
+import TabPanel from './tab-panel';
+import Tabs from './tabs';
+
+interface Signature {
+  Args: {};
+}
+
+// Modal shell for the combined chooser. Driven by the
+// `markdown-embed-chooser` service: opens when a `chooseCardOrFile` /
+// `editEmbed` call lands, closes when the user picks/cancels or hits Escape.
+// Both tabs stay mounted while the modal is open so each tab keeps its own
+// search/selection/W×H state across switches.
+export default class MarkdownEmbedChooserModal extends Component<Signature> {
+  @service declare private markdownEmbedChooser: MarkdownEmbedChooserService;
+
+  // User clicks pinned to the request they were made against. The getter
+  // ignores them once a new request arrives so the next opening starts on
+  // its own `defaultTab`.
+  @tracked private manuallySelectedTab: MarkdownEmbedRefType | undefined;
+  @tracked
+  private manualSelectionRequest: MarkdownEmbedChooserRequest | undefined;
+
+  constructor(owner: Owner, args: Signature['Args']) {
+    super(owner, args);
+    // Registers the global bridge `chooseMarkdownEmbed` / `editMarkdownEmbed`
+    // in runtime-common dispatch to. Mirrors the card-chooser/file-chooser
+    // pattern so the base-realm markdown editor can open the modal without a
+    // direct host import.
+    (globalThis as any)._CARDSTACK_MARKDOWN_EMBED_CHOOSER = {
+      chooseCardOrFile: (opts: { defaultTab?: MarkdownEmbedRefType }) =>
+        this.markdownEmbedChooser.chooseCardOrFile(opts),
+      editEmbed: (
+        target: Parameters<MarkdownEmbedChooserService['editEmbed']>[0],
+      ) => this.markdownEmbedChooser.editEmbed(target),
+    };
+    registerDestructor(this, () => {
+      delete (globalThis as any)._CARDSTACK_MARKDOWN_EMBED_CHOOSER;
+    });
+  }
+
+  private get request() {
+    return this.markdownEmbedChooser.currentRequest;
+  }
+
+  get activeTab(): MarkdownEmbedRefType {
+    let req = this.request;
+    if (
+      this.manualSelectionRequest === req &&
+      this.manuallySelectedTab !== undefined
+    ) {
+      return this.manuallySelectedTab;
+    }
+    return req?.defaultTab ?? 'card';
+  }
+
+  @action
+  private setActiveTab(tab: MarkdownEmbedRefType) {
+    this.manualSelectionRequest = this.request;
+    this.manuallySelectedTab = tab;
+  }
+
+  @action
+  private handleInsertCard(bfm: string, url: string) {
+    this.markdownEmbedChooser.resolve({ refType: 'card', url, bfm });
+  }
+
+  @action
+  private handleInsertFile(bfm: string, url: string) {
+    this.markdownEmbedChooser.resolve({ refType: 'file', url, bfm });
+  }
+
+  @action
+  private handleRemove() {
+    this.markdownEmbedChooser.resolve({ remove: true });
+  }
+
+  @action
+  private handleClose() {
+    this.markdownEmbedChooser.resolve(undefined);
+  }
+
+  @action
+  private handleKeydown(event: Event) {
+    if ((event as KeyboardEvent).key === 'Escape') {
+      this.handleClose();
+    }
+  }
+
+  // Edit-mode preload is scoped to the matching tab. The other tab still
+  // opens its mini chooser per Zeplin 08B.
+  private get cardInitialTarget() {
+    let it = this.request?.initialTarget;
+    return it?.refType === 'card' ? it : undefined;
+  }
+
+  private get fileInitialTarget() {
+    let it = this.request?.initialTarget;
+    return it?.refType === 'file' ? it : undefined;
+  }
+
+  <template>
+    {{#if this.request}}
+      <ModalContainer
+        class='markdown-embed-chooser-modal'
+        @title=''
+        @onClose={{this.handleClose}}
+        @size='large'
+        @centered={{true}}
+        @cardContainerClass='markdown-embed-chooser-modal__container'
+        {{focusTrap
+          isActive=true
+          focusTrapOptions=(hash allowOutsideClick=true)
+        }}
+        {{on 'keydown' this.handleKeydown}}
+        data-test-markdown-embed-chooser-modal
+      >
+        <:content>
+          <Tabs @activeTab={{this.activeTab}}>
+            <:cards>
+              <TabPanel
+                @refType='card'
+                @activeTab={{this.activeTab}}
+                @onTabChange={{this.setActiveTab}}
+                @onInsert={{this.handleInsertCard}}
+                @initialTarget={{this.cardInitialTarget}}
+                @onRemove={{this.handleRemove}}
+              />
+            </:cards>
+            <:files>
+              <TabPanel
+                @refType='file'
+                @activeTab={{this.activeTab}}
+                @onTabChange={{this.setActiveTab}}
+                @onInsert={{this.handleInsertFile}}
+                @initialTarget={{this.fileInitialTarget}}
+                @onRemove={{this.handleRemove}}
+              />
+            </:files>
+          </Tabs>
+        </:content>
+      </ModalContainer>
+    {{/if}}
+    <style scoped>
+      /* Collapse the (empty) modal header band to nothing. With @title='' and
+         no <:header> content it holds only the built-in close button, which is
+         position:absolute and out of flow — so the band disappears while the
+         × keeps floating at the modal's top-right corner. */
+      .markdown-embed-chooser-modal :deep(.dialog-box__header) {
+        min-height: 0;
+        padding: 0;
+      }
+      /* Full-bleed body: the two columns and the divider between them run to
+         the modal edges, so the content gets no padding of its own — each
+         column's inner components supply their own insets. */
+      .markdown-embed-chooser-modal :deep(.dialog-box__content) {
+        display: flex;
+        flex-direction: column;
+        padding: 0;
+      }
+      :deep(.markdown-embed-chooser-modal__container) {
+        height: 36rem;
+      }
+      /* Re-center the fixed-height modal box vertically. Operator mode ships a
+         global `.operator-mode .boxel-modal__inner { display: block }` that
+         outranks boxel-ui's base `.boxel-modal__inner { display: flex }`, which
+         drops the inner's flex centering and top-aligns our 36rem box. Restore
+         flex on our own inner so `@centered` actually centers it. */
+      .markdown-embed-chooser-modal > :deep(.boxel-modal__inner) {
+        display: flex;
+      }
+    </style>
+  </template>
+}
diff --git a/packages/host/app/components/markdown-embed-chooser/pane.gts b/packages/host/app/components/markdown-embed-chooser/pane.gts
index 16edfe376df..f3d3a84c11b 100644
--- a/packages/host/app/components/markdown-embed-chooser/pane.gts
+++ b/packages/host/app/components/markdown-embed-chooser/pane.gts
@@ -1,5 +1,6 @@
 import { on } from '@ember/modifier';
 import { action } from '@ember/object';
+import type Owner from '@ember/owner';
 
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
@@ -30,7 +31,12 @@ import MarkdownEmbedPreview from './preview';
 
 type EmbedFormat = 'atom' | 'embedded' | 'fitted' | 'isolated';
 type FormatCategory = 'atom' | 'embedded' | 'fitted' | 'isolated' | 'custom';
-type OptionValue = 'atom' | 'embedded' | 'isolated' | FittedFormatId | 'custom';
+export type OptionValue =
+  | 'atom'
+  | 'embedded'
+  | 'isolated'
+  | FittedFormatId
+  | 'custom';
 
 interface FormatOption {
   value: OptionValue;
@@ -88,13 +94,35 @@ function buildFormatOptions(): FormatOption[] {
 interface Signature {
   Element: HTMLElement;
   Args: {
-    // Resolved instance being previewed. Its `id` is the BFM ref URL.
+    // 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;
     // Which BFM keyword to emit: `:card[...]` vs `:file[...]`.
     refType: 'card' | 'file';
     // Receives the serialized BFM directive when the CTA is clicked. The host
     // owns actual cursor insertion (a later ticket).
     onInsert: (bfm: string) => void;
+    // Edit-mode preload: seed the format dropdown, W×H inputs, and placement
+    // toggle from the BFM directive the user is editing. Read once at
+    // construction; later updates are ignored so the pane is free to mutate
+    // its own state as the user edits.
+    initialFormat?: OptionValue;
+    initialWidth?: number | string;
+    initialHeight?: number;
+    initialKind?: 'inline' | 'block';
+    // URL of the placed target the user is editing. Distinct from
+    // `target.id` because the resolved instance arrives asynchronously —
+    // without this, the dirty check would briefly flip true as soon as the
+    // target loads.
+    initialTargetUrl?: string;
+    // Fired with `true` once the pane's state diverges from the initial
+    // preload (and back to `false` if it matches again). The parent uses this
+    // to flip the CTA label between 'DONE' and 'ACCEPT' in edit mode.
+    onDirtyChange?: (dirty: boolean) => void;
+    // Overrides the dynamic "Insert as …" CTA label. Used in edit mode to
+    // show 'DONE' (clean) or 'ACCEPT' (dirty) per the design spec.
+    ctaLabelOverride?: string;
   };
 }
 
@@ -113,6 +141,46 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
   @tracked private widthInput = '';
   @tracked private heightInput = '';
 
+  // Frozen snapshot of the initial pane state, captured once on mount from the
+  // edit-mode preload args. Used by `dirty` to detect divergence so the parent
+  // can flip the CTA between DONE and ACCEPT.
+  private initialSelectedValue: OptionValue;
+  private initialKind: 'inline' | 'block';
+  private initialWidthInput: string;
+  private initialHeightInput: string;
+  private initialTargetUrl: string | undefined;
+
+  constructor(owner: Owner, args: Signature['Args']) {
+    super(owner, args);
+    if (args.initialFormat !== undefined) {
+      this.selectedValue = args.initialFormat;
+    }
+    if (args.initialKind !== undefined) {
+      this.kind = args.initialKind;
+    } else if (args.initialFormat !== undefined) {
+      // Mirror `selectFormat`'s placement default (atom → inline, sized →
+      // block) when no explicit initial kind is supplied.
+      let cat = this.formatOptions.find(
+        (o) => o.value === args.initialFormat,
+      )?.category;
+      this.kind = cat === 'atom' ? 'inline' : 'block';
+    }
+    if (args.initialWidth !== undefined) {
+      this.widthInput = String(args.initialWidth);
+    }
+    if (args.initialHeight !== undefined) {
+      this.heightInput = String(args.initialHeight);
+    }
+    this.initialSelectedValue = this.selectedValue;
+    this.initialKind = this.kind;
+    this.initialWidthInput = this.widthInput;
+    this.initialHeightInput = this.heightInput;
+    // `initialTargetUrl` arg wins over `args.target?.id` because the resolved
+    // instance is loaded asynchronously — at construction time the parent
+    // already knows the URL but the store has not yet returned the instance.
+    this.initialTargetUrl = args.initialTargetUrl ?? args.target.id;
+  }
+
   private get selectedOption(): FormatOption {
     return (
       this.formatOptions.find((o) => o.value === this.selectedValue) ??
@@ -180,9 +248,37 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
   }
 
   private get ctaLabel(): string {
+    if (this.args.ctaLabelOverride !== undefined) {
+      return this.args.ctaLabelOverride;
+    }
     return `Insert as ${this.categoryLabel}`;
   }
 
+  // True once any tracked piece of state (format, placement, W×H, or the
+  // resolved target URL) has diverged from the constructor snapshot. The
+  // parent watches via `onDirtyChange` to drive its CTA label.
+  get isDirty(): boolean {
+    return (
+      this.selectedValue !== this.initialSelectedValue ||
+      this.kind !== this.initialKind ||
+      this.widthInput !== this.initialWidthInput ||
+      this.heightInput !== this.initialHeightInput ||
+      this.args.target.id !== this.initialTargetUrl
+    );
+  }
+
+  // Re-runs on every render. Auto-tracking re-evaluates `isDirty` whenever any
+  // of its dependencies changes; the equality guard keeps onDirtyChange from
+  // firing on every render in addition to genuine transitions.
+  private lastReportedDirty: boolean | undefined;
+  private reportDirty = () => {
+    let dirty = this.isDirty;
+    if (dirty !== this.lastReportedDirty) {
+      this.lastReportedDirty = dirty;
+      this.args.onDirtyChange?.(dirty);
+    }
+  };
+
   // Size specifier for the chosen format. Atom is the default for inline
   // placement, so an inline atom embed emits the size-less `:card[url]`;
   // every other combination carries an explicit specifier so the rendered
@@ -210,6 +306,9 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
 
   private get bfmString(): string {
     let url = this.args.target.id;
+    if (!url) {
+      return '';
+    }
     return serializeBfmRef(this.args.refType, url, {
       kind: this.kind,
       size: this.sizeSpecifier,
@@ -266,10 +365,13 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
 
   @action
   private insert() {
-    this.args.onInsert(this.bfmString);
+    let bfm = this.bfmString;
+    if (!bfm) return;
+    this.args.onInsert(bfm);
   }
 
   <template>
+    {{this.reportDirty}}
     <section
       class='markdown-embed-preview-pane'
       data-test-markdown-embed-preview-pane
@@ -389,7 +491,9 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
         width: 100%;
         height: 100%;
         min-height: 0;
-        background-color: var(--boxel-light);
+        /* Inherit the preview column's off-white surface; the inner card
+           viewport supplies its own background. */
+        background-color: transparent;
       }
       .markdown-embed-preview-pane__header {
         flex: 0 0 auto;
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
new file mode 100644
index 00000000000..d8fbad31e3a
--- /dev/null
+++ b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
@@ -0,0 +1,372 @@
+import { on } from '@ember/modifier';
+import { action } from '@ember/object';
+import type Owner from '@ember/owner';
+import { service } from '@ember/service';
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import { restartableTask } from 'ember-concurrency';
+
+import { BoxelButton } from '@cardstack/boxel-ui/components';
+import { eq } from '@cardstack/boxel-ui/helpers';
+
+import { isCardErrorJSONAPI } from '@cardstack/runtime-common';
+
+import {
+  type BfmSizeSpec,
+  fileNameFromUrl,
+  parseBfmSizeSpec,
+} from '@cardstack/runtime-common/bfm-card-references';
+
+import MiniCardChooser from '@cardstack/host/components/card-chooser/mini';
+import MiniFileChooser from '@cardstack/host/components/file-chooser/mini';
+
+import type {
+  MarkdownEmbedInitialTarget,
+  MarkdownEmbedRefType,
+} from '@cardstack/host/services/markdown-embed-chooser';
+import type StoreService from '@cardstack/host/services/store';
+
+import type { CardDef, FileDef } from 'https://cardstack.com/base/card-api';
+
+import MarkdownEmbedPreviewPane, { type OptionValue } from './pane';
+import TabPills from './tab-pills';
+
+interface Signature {
+  Element: HTMLDivElement;
+  Args: {
+    refType: MarkdownEmbedRefType;
+    // The chooser's active tab + switch handler. The segmented pill control
+    // lives at the top of this panel's left (search) column, so each visible
+    // tab carries its own pills directly above its search bar — matching the
+    // design where the tabs sit inside the search section, not as a
+    // full-width bar across the modal.
+    activeTab: MarkdownEmbedRefType;
+    onTabChange: (tab: MarkdownEmbedRefType) => void;
+    onInsert: (bfm: string, url: string) => void;
+    // Optional edit-mode preload for this tab. When set, the tab starts in
+    // `current` mode showing the placed target with Replace / Remove buttons;
+    // the pane is seeded with the matching size + placement.
+    initialTarget?: MarkdownEmbedInitialTarget;
+    // Fired when the user clicks "Remove" in `current` mode. The modal
+    // resolves its deferred with `{ remove: true }`.
+    onRemove?: () => void;
+  };
+}
+
+// One tab of the combined chooser: pairs the matching mini chooser (left
+// panel) with the shared preview pane (right panel). Owns the tab-local
+// `selectedTarget` so left-panel state — search query, highlighted row,
+// scroll position — and pane state survive a switch to the other tab. In
+// edit mode (`initialTarget` set), the left panel renders a "current target"
+// tile with Replace / Remove buttons instead of the mini chooser; clicking
+// Replace flips it back to the chooser so the user can swap in a new ref.
+export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
+  @service declare private store: StoreService;
+
+  @tracked private selectedTarget: CardDef | FileDef | undefined;
+  @tracked private selectedUrl: string | undefined;
+  @tracked private mode: 'choose' | 'current' = 'choose';
+  @tracked private dirty = false;
+
+  private initialPaneFormat: OptionValue | undefined;
+  private initialPaneWidth: number | string | undefined;
+  private initialPaneHeight: number | undefined;
+  private initialPaneKind: 'inline' | 'block' | undefined;
+
+  constructor(owner: Owner, args: Signature['Args']) {
+    super(owner, args);
+    let it = args.initialTarget;
+    if (it) {
+      this.mode = 'current';
+      this.selectedUrl = it.url;
+      let derived = derivePaneSeeds(normalizeSizeSpec(it.sizeSpec));
+      this.initialPaneFormat = derived.format;
+      this.initialPaneWidth = derived.width;
+      this.initialPaneHeight = derived.height;
+      this.initialPaneKind = derived.kind;
+      this.loadTarget.perform(it.url, it.refType);
+    }
+  }
+
+  private get isEditMode(): boolean {
+    return !!this.args.initialTarget;
+  }
+
+  // '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;
+    return this.dirty ? 'ACCEPT' : 'DONE';
+  }
+
+  private get currentTargetLabel(): string {
+    let t = this.selectedTarget;
+    if (!t) return this.selectedUrl ?? '';
+    if (this.args.refType === 'file') {
+      return fileNameFromUrl(t.id ?? this.selectedUrl ?? '');
+    }
+    return (t as CardDef).cardTitle ?? t.id ?? this.selectedUrl ?? '';
+  }
+
+  @action
+  private onCardSelect(url: string) {
+    this.loadTarget.perform(url, 'card');
+  }
+
+  @action
+  private onFileSelect(url: string) {
+    this.loadTarget.perform(url, 'file');
+  }
+
+  // Restart on every pick so a slow earlier load can't stomp the newer one.
+  private loadTarget = restartableTask(
+    async (url: string, refType: MarkdownEmbedRefType) => {
+      this.selectedUrl = url;
+      let result =
+        refType === 'card'
+          ? await this.store.get(url)
+          : await this.store.get<FileDef>(url, { type: 'file-meta' });
+      if (isCardErrorJSONAPI(result)) {
+        this.selectedTarget = undefined;
+        return;
+      }
+      this.selectedTarget = result as CardDef | FileDef;
+    },
+  );
+
+  @action
+  private handleInsert(bfm: string) {
+    let url = this.selectedTarget?.id ?? this.selectedUrl;
+    if (!url) return;
+    this.args.onInsert(bfm, url);
+  }
+
+  @action
+  private onPaneDirtyChange(dirty: boolean) {
+    this.dirty = dirty;
+  }
+
+  @action
+  private startReplace() {
+    this.mode = 'choose';
+  }
+
+  @action
+  private clickRemove() {
+    this.args.onRemove?.();
+  }
+
+  <template>
+    <div
+      class='markdown-embed-chooser-tab-panel'
+      data-test-markdown-embed-chooser-tab-panel={{@refType}}
+      ...attributes
+    >
+      <div class='markdown-embed-chooser-tab-panel__left'>
+        {{! Both tab panels stay mounted to preserve their state, so the pills
+          render only in the active one — a single set of tabs in the DOM. }}
+        {{#if (eq @refType @activeTab)}}
+          <div class='markdown-embed-chooser-tab-panel__tabbar'>
+            <TabPills @activeTab={{@activeTab}} @onTabChange={{@onTabChange}} />
+          </div>
+        {{/if}}
+        {{#if (eq this.mode 'current')}}
+          <div
+            class='markdown-embed-chooser-tab-panel__current'
+            data-test-markdown-embed-chooser-current
+          >
+            <span
+              class='markdown-embed-chooser-tab-panel__current-label'
+              data-test-markdown-embed-chooser-current-label
+            >
+              {{this.currentTargetLabel}}
+            </span>
+            <div class='markdown-embed-chooser-tab-panel__current-actions'>
+              <BoxelButton
+                {{on 'click' this.startReplace}}
+                data-test-markdown-embed-chooser-replace
+              >
+                {{#if (eq @refType 'card')}}
+                  Replace Card
+                {{else}}
+                  Replace File
+                {{/if}}
+              </BoxelButton>
+              <BoxelButton
+                @kind='secondary-light'
+                {{on 'click' this.clickRemove}}
+                data-test-markdown-embed-chooser-remove
+              >
+                {{#if (eq @refType 'card')}}
+                  Remove Card
+                {{else}}
+                  Remove File
+                {{/if}}
+              </BoxelButton>
+            </div>
+          </div>
+        {{else if (eq @refType 'card')}}
+          <MiniCardChooser
+            @onSelect={{this.onCardSelect}}
+            @selected={{this.selectedUrl}}
+          />
+        {{else}}
+          <MiniFileChooser
+            @onSelect={{this.onFileSelect}}
+            @onHighlight={{this.onFileSelect}}
+            @selected={{this.selectedUrl}}
+          />
+        {{/if}}
+      </div>
+      <div class='markdown-embed-chooser-tab-panel__right'>
+        {{#if this.selectedTarget}}
+          <MarkdownEmbedPreviewPane
+            @target={{this.selectedTarget}}
+            @refType={{@refType}}
+            @onInsert={{this.handleInsert}}
+            @initialFormat={{this.initialPaneFormat}}
+            @initialWidth={{this.initialPaneWidth}}
+            @initialHeight={{this.initialPaneHeight}}
+            @initialKind={{this.initialPaneKind}}
+            @initialTargetUrl={{@initialTarget.url}}
+            @ctaLabelOverride={{this.ctaLabelOverride}}
+            @onDirtyChange={{this.onPaneDirtyChange}}
+          />
+        {{else}}
+          <p
+            class='markdown-embed-chooser-tab-panel__empty'
+            data-test-markdown-embed-preview-empty
+          >
+            Search for a
+            {{@refType}}
+            &amp; preview its format here
+          </p>
+        {{/if}}
+      </div>
+    </div>
+    <style scoped>
+      .markdown-embed-chooser-tab-panel {
+        display: flex;
+        width: 100%;
+        height: 100%;
+        min-height: 0;
+        background-color: var(--boxel-light);
+      }
+      .markdown-embed-chooser-tab-panel__left,
+      .markdown-embed-chooser-tab-panel__right {
+        min-width: 0;
+        min-height: 0;
+        overflow: hidden;
+      }
+      /* The chooser column is narrower than the preview column (~2:3), per the
+         design. A single full-height divider between the two columns — no boxed
+         borders, so the panels read as one continuous surface. The left
+         column stacks the tab pills above the mini chooser. */
+      .markdown-embed-chooser-tab-panel__left {
+        flex: 2 1 0;
+        display: flex;
+        flex-direction: column;
+        border-right: 1px solid var(--boxel-300);
+      }
+      /* Pills sit at the top of the search column, directly above the search
+         bar; the chooser below fills the remaining height. */
+      .markdown-embed-chooser-tab-panel__tabbar {
+        flex: 0 0 auto;
+        display: flex;
+        align-items: center;
+        padding: var(--boxel-sp-sm) var(--boxel-sp-xs) 0;
+      }
+      /* The chooser (or current-target tile) fills the column below the pills.
+         The mini choosers set their own `height: 100%`, which would resolve
+         against the full column height and overflow past the pills — grow to
+         the remaining space instead. */
+      .markdown-embed-chooser-tab-panel__left > :deep(.mini-card-chooser),
+      .markdown-embed-chooser-tab-panel__left > :deep(.mini-file-chooser),
+      .markdown-embed-chooser-tab-panel__current {
+        flex: 1 1 auto;
+        min-height: 0;
+        height: auto;
+      }
+      .markdown-embed-chooser-tab-panel__right {
+        flex: 3 1 0;
+        display: flex;
+        flex-direction: column;
+        min-height: 0;
+        /* The preview column reads as an off-white surface, distinct from the
+           white chooser column on the left. */
+        background-color: #fbf8f8;
+      }
+      /* Centered placeholder shown until a row is picked and its instance
+         resolves; the pane mounts in its place once a target arrives. */
+      .markdown-embed-chooser-tab-panel__empty {
+        flex: 1 1 auto;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        margin: 0;
+        padding: var(--boxel-sp);
+        font: var(--boxel-font-sm);
+        color: var(--boxel-450);
+        text-align: center;
+      }
+      .markdown-embed-chooser-tab-panel__current {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: var(--boxel-sp);
+        padding: var(--boxel-sp);
+        text-align: center;
+      }
+      .markdown-embed-chooser-tab-panel__current-label {
+        font: 600 var(--boxel-font);
+        word-break: break-word;
+      }
+      .markdown-embed-chooser-tab-panel__current-actions {
+        display: flex;
+        gap: var(--boxel-sp-xs);
+      }
+    </style>
+  </template>
+}
+
+function normalizeSizeSpec(
+  input: BfmSizeSpec | string | undefined,
+): BfmSizeSpec | undefined {
+  if (!input) return undefined;
+  if (typeof input === 'string') {
+    return parseBfmSizeSpec(input) ?? undefined;
+  }
+  return input;
+}
+
+interface PaneSeeds {
+  format?: OptionValue;
+  width?: number | string;
+  height?: number;
+  kind?: 'inline' | 'block';
+}
+
+function derivePaneSeeds(spec: BfmSizeSpec | undefined): PaneSeeds {
+  if (!spec) {
+    return {};
+  }
+  if (spec.format === 'atom') {
+    return { format: 'atom', kind: 'inline' };
+  }
+  if (spec.format === 'embedded') {
+    return { format: 'embedded', kind: 'block' };
+  }
+  if (spec.format === 'isolated') {
+    return { format: 'isolated', kind: 'block' };
+  }
+  // Fitted with optional W×H.
+  return {
+    format: 'custom',
+    width: spec.width,
+    height: spec.height,
+    kind: 'block',
+  };
+}
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-pills.gts b/packages/host/app/components/markdown-embed-chooser/tab-pills.gts
new file mode 100644
index 00000000000..4a6ec3cea63
--- /dev/null
+++ b/packages/host/app/components/markdown-embed-chooser/tab-pills.gts
@@ -0,0 +1,94 @@
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+
+import { eq } from '@cardstack/boxel-ui/helpers';
+
+import type { MarkdownEmbedRefType } from '@cardstack/host/services/markdown-embed-chooser';
+
+interface Signature {
+  Element: HTMLDivElement;
+  Args: {
+    activeTab: MarkdownEmbedRefType;
+    onTabChange: (tab: MarkdownEmbedRefType) => void;
+  };
+}
+
+// Segmented pill control for the combined chooser's two tabs. Sits at the top
+// of the active tab's left (search) column, directly above its search bar; the
+// matching tabpanels render alongside in the modal body. Button ids are
+// referenced by the panels' `aria-labelledby`, so they're kept stable here.
+const MarkdownEmbedChooserTabPills: TemplateOnlyComponent<Signature> =
+  <template>
+    <div
+      class='markdown-embed-chooser-tab-pills'
+      role='tablist'
+      aria-label='Choose card or file'
+      ...attributes
+    >
+      <button
+        type='button'
+        role='tab'
+        id='markdown-embed-chooser-tab-cards'
+        aria-controls='markdown-embed-chooser-panel-cards'
+        aria-selected={{if (eq @activeTab 'card') 'true' 'false'}}
+        tabindex={{if (eq @activeTab 'card') '0' '-1'}}
+        class='markdown-embed-chooser-tab-pills__tab
+          {{if (eq @activeTab "card") "is-active"}}'
+        data-test-markdown-embed-chooser-tab='card'
+        {{on 'click' (fn @onTabChange 'card')}}
+      >
+        Cards
+      </button>
+      <button
+        type='button'
+        role='tab'
+        id='markdown-embed-chooser-tab-files'
+        aria-controls='markdown-embed-chooser-panel-files'
+        aria-selected={{if (eq @activeTab 'file') 'true' 'false'}}
+        tabindex={{if (eq @activeTab 'file') '0' '-1'}}
+        class='markdown-embed-chooser-tab-pills__tab
+          {{if (eq @activeTab "file") "is-active"}}'
+        data-test-markdown-embed-chooser-tab='file'
+        {{on 'click' (fn @onTabChange 'file')}}
+      >
+        Files
+      </button>
+    </div>
+    <style scoped>
+      .markdown-embed-chooser-tab-pills {
+        display: flex;
+        width: 100%;
+        gap: var(--boxel-sp-4xs);
+        padding: var(--boxel-sp-5xs);
+        border-radius: 999px;
+        background-color: var(--boxel-200);
+      }
+      .markdown-embed-chooser-tab-pills__tab {
+        appearance: none;
+        flex: 1 1 0;
+        border: none;
+        background: transparent;
+        padding: var(--boxel-sp-4xs) var(--boxel-sp);
+        border-radius: 999px;
+        font: 600 var(--boxel-font-sm);
+        color: var(--boxel-450);
+        cursor: pointer;
+        line-height: 1.4;
+      }
+      .markdown-embed-chooser-tab-pills__tab:hover {
+        color: var(--boxel-dark);
+      }
+      .markdown-embed-chooser-tab-pills__tab.is-active {
+        color: var(--boxel-dark);
+        background-color: var(--boxel-light);
+        box-shadow: var(--boxel-box-shadow-sm, 0 1px 2px rgba(0, 0, 0, 0.15));
+      }
+      .markdown-embed-chooser-tab-pills__tab:focus-visible {
+        outline: 2px solid var(--boxel-highlight);
+        outline-offset: 2px;
+      }
+    </style>
+  </template>;
+
+export default MarkdownEmbedChooserTabPills;
diff --git a/packages/host/app/components/markdown-embed-chooser/tabs.gts b/packages/host/app/components/markdown-embed-chooser/tabs.gts
new file mode 100644
index 00000000000..e376d9434ac
--- /dev/null
+++ b/packages/host/app/components/markdown-embed-chooser/tabs.gts
@@ -0,0 +1,66 @@
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+import { eq } from '@cardstack/boxel-ui/helpers';
+
+import type { MarkdownEmbedRefType } from '@cardstack/host/services/markdown-embed-chooser';
+
+interface Signature {
+  Element: HTMLDivElement;
+  Args: {
+    activeTab: MarkdownEmbedRefType;
+  };
+  Blocks: {
+    cards: [];
+    files: [];
+  };
+}
+
+// The two tabpanels for the combined chooser. The matching segmented pill
+// control sits at the top of each panel's left search column (see
+// `tab-pills.gts`); each panel's `aria-labelledby` points back to its pill
+// button by id. Both panels stay
+// mounted — the inactive one is `display: none` rather than `{{#if}}`'d out —
+// so each tab's mini-chooser keeps its search query, highlighted row, scroll
+// position, and the pane's W×H / format selection across a switch.
+const MarkdownEmbedChooserTabs: TemplateOnlyComponent<Signature> = <template>
+  <div class='markdown-embed-chooser-tabs' ...attributes>
+    <div
+      role='tabpanel'
+      id='markdown-embed-chooser-panel-cards'
+      aria-labelledby='markdown-embed-chooser-tab-cards'
+      class='markdown-embed-chooser-tabs__panel
+        {{unless (eq @activeTab "card") "is-hidden"}}'
+      data-test-markdown-embed-chooser-panel='card'
+    >
+      {{yield to='cards'}}
+    </div>
+    <div
+      role='tabpanel'
+      id='markdown-embed-chooser-panel-files'
+      aria-labelledby='markdown-embed-chooser-tab-files'
+      class='markdown-embed-chooser-tabs__panel
+        {{unless (eq @activeTab "file") "is-hidden"}}'
+      data-test-markdown-embed-chooser-panel='file'
+    >
+      {{yield to='files'}}
+    </div>
+  </div>
+  <style scoped>
+    .markdown-embed-chooser-tabs {
+      display: flex;
+      flex-direction: column;
+      width: 100%;
+      height: 100%;
+      min-height: 0;
+    }
+    .markdown-embed-chooser-tabs__panel {
+      flex: 1 1 auto;
+      min-height: 0;
+    }
+    .markdown-embed-chooser-tabs__panel.is-hidden {
+      display: none;
+    }
+  </style>
+</template>;
+
+export default MarkdownEmbedChooserTabs;
diff --git a/packages/host/app/components/operator-mode/container.gts b/packages/host/app/components/operator-mode/container.gts
index 9d2d4adacec..898d40ec603 100644
--- a/packages/host/app/components/operator-mode/container.gts
+++ b/packages/host/app/components/operator-mode/container.gts
@@ -39,6 +39,7 @@ import type { CardContext } from 'https://cardstack.com/base/card-api';
 import CardChooserModal from '../card-chooser/modal';
 import SearchResults from '../card-search/search-results';
 import FileChooserModal from '../file-chooser/modal';
+import MarkdownEmbedChooserModal from '../markdown-embed-chooser/modal';
 import { Submodes } from '../submode-switcher';
 
 import CreateListingModal from './create-listing-modal';
@@ -147,6 +148,7 @@ export default class OperatorModeContainer extends Component<Signature> {
       <FileChooserModal />
       <CreateListingModal />
       <CardChooserModal />
+      <MarkdownEmbedChooserModal />
       <FromElseWhere @name='modal-elsewhere' />
 
       {{#if
diff --git a/packages/host/app/lib/codemirror-context.ts b/packages/host/app/lib/codemirror-context.ts
index 8e80c89fbb0..7c6d19eed55 100644
--- a/packages/host/app/lib/codemirror-context.ts
+++ b/packages/host/app/lib/codemirror-context.ts
@@ -44,6 +44,11 @@ import {
   keymap,
 } from '@codemirror/view';
 
+import {
+  type BfmRefRange,
+  extractBfmRefRanges,
+} from '@cardstack/runtime-common/bfm-card-references';
+
 // ── Card widget target interface ────────────────────────────────────────────
 
 export interface CardWidgetTarget {
@@ -1043,6 +1048,10 @@ export interface SelectionInfo {
     strikethrough: boolean;
     link: boolean;
   };
+  // BFM `:card[…]` / `::file[…]` directive the cursor head is currently
+  // inside. Undefined when the cursor is outside every directive. Drives
+  // the toolbar's Add-vs-Edit-embed swap.
+  currentRef?: BfmRefRange;
 }
 
 function detectFormats(
@@ -1117,33 +1126,49 @@ function createEditorState(options: CreateEditorStateOptions): EditorState {
       override: [slashSource],
       defaultKeymap: true,
     }),
-    EditorView.updateListener.of((update: ViewUpdate) => {
-      if (update.docChanged) {
-        onDocChange(update.state.doc.toString());
-      }
-      if (
-        onSelectionChange &&
-        (update.selectionSet || update.docChanged || update.focusChanged)
-      ) {
-        let { from, to } = update.state.selection.main;
-        let hasSelection = from !== to;
-        onSelectionChange({
-          hasSelection,
-          hasFocus: update.view.hasFocus,
-          from,
-          to,
-          formats: hasSelection
-            ? detectFormats(update.state, from, to)
-            : {
-                bold: false,
-                italic: false,
-                code: false,
-                strikethrough: false,
-                link: false,
-              },
-        });
-      }
-    }),
+    (() => {
+      // BFM ref ranges cached across selection-only updates — `extractBfmRefRanges`
+      // is a doc-wide string scan, so recompute only when the doc changes.
+      let cachedRanges: BfmRefRange[] = extractBfmRefRanges(content);
+
+      return EditorView.updateListener.of((update: ViewUpdate) => {
+        if (update.docChanged) {
+          let nextDoc = update.state.doc.toString();
+          onDocChange(nextDoc);
+          cachedRanges = extractBfmRefRanges(nextDoc);
+        }
+        if (
+          onSelectionChange &&
+          (update.selectionSet || update.docChanged || update.focusChanged)
+        ) {
+          let { from, to } = update.state.selection.main;
+          let hasSelection = from !== to;
+          let head = update.state.selection.main.head;
+          // A directive owns positions in `[from, to)`. Caret on the closing
+          // `]` (== to) reads as "outside" so post-directive typing isn't
+          // surfaced as edit-this-embed.
+          let currentRef = cachedRanges.find(
+            (r) => head >= r.from && head < r.to,
+          );
+          onSelectionChange({
+            hasSelection,
+            hasFocus: update.view.hasFocus,
+            from,
+            to,
+            formats: hasSelection
+              ? detectFormats(update.state, from, to)
+              : {
+                  bold: false,
+                  italic: false,
+                  code: false,
+                  strikethrough: false,
+                  link: false,
+                },
+            currentRef,
+          });
+        }
+      });
+    })(),
     EditorView.lineWrapping,
   ];
 
diff --git a/packages/host/app/lib/externals.ts b/packages/host/app/lib/externals.ts
index 19719801b03..c0dc99cde14 100644
--- a/packages/host/app/lib/externals.ts
+++ b/packages/host/app/lib/externals.ts
@@ -202,6 +202,10 @@ export function shimExternals(virtualNetwork: VirtualNetwork) {
     id: '@cardstack/runtime-common/marked-sync',
     resolve: () => import('@cardstack/runtime-common/marked-sync'),
   });
+  virtualNetwork.shimAsyncModule({
+    id: '@cardstack/runtime-common/bfm-card-references',
+    resolve: () => import('@cardstack/runtime-common/bfm-card-references'),
+  });
 
   shimModulesForLiveTests(virtualNetwork);
 
diff --git a/packages/host/app/services/markdown-embed-chooser.ts b/packages/host/app/services/markdown-embed-chooser.ts
new file mode 100644
index 00000000000..fdb0b254094
--- /dev/null
+++ b/packages/host/app/services/markdown-embed-chooser.ts
@@ -0,0 +1,87 @@
+import Service from '@ember/service';
+
+import { tracked } from '@glimmer/tracking';
+
+import { Deferred } from '@cardstack/runtime-common';
+
+import type { BfmSizeSpec } from '@cardstack/runtime-common/bfm-card-references';
+
+export type MarkdownEmbedRefType = 'card' | 'file';
+
+export interface MarkdownEmbedResult {
+  refType: MarkdownEmbedRefType;
+  url: string;
+  bfm: string;
+}
+
+export type MarkdownEmbedResolution =
+  | MarkdownEmbedResult
+  | { remove: true }
+  | undefined;
+
+export interface MarkdownEmbedInitialTarget {
+  refType: MarkdownEmbedRefType;
+  url: string;
+  // Either a pre-parsed `BfmSizeSpec` (from extractBfmRefRanges) or the raw
+  // specifier text after `|`. The pane parses the string form itself.
+  sizeSpec?: BfmSizeSpec | string;
+}
+
+export interface MarkdownEmbedChooserRequest {
+  defaultTab: MarkdownEmbedRefType;
+  initialTarget?: MarkdownEmbedInitialTarget;
+  deferred: Deferred<MarkdownEmbedResolution>;
+}
+
+// Single in-flight request at a time — the modal is the only consumer. If
+// another `chooseCardOrFile`/`editEmbed` call lands while a modal is already
+// open, the prior caller is resolved with `undefined` (cancel) before the new
+// request displaces it.
+export default class MarkdownEmbedChooserService extends Service {
+  @tracked currentRequest: MarkdownEmbedChooserRequest | undefined;
+
+  chooseCardOrFile(
+    opts: { defaultTab?: MarkdownEmbedRefType } = {},
+  ): Promise<MarkdownEmbedResolution> {
+    return this.open({ defaultTab: opts.defaultTab ?? 'card' });
+  }
+
+  editEmbed(
+    target: MarkdownEmbedInitialTarget,
+  ): Promise<MarkdownEmbedResolution> {
+    return this.open({
+      defaultTab: target.refType,
+      initialTarget: target,
+    });
+  }
+
+  resolve(result: MarkdownEmbedResolution) {
+    let req = this.currentRequest;
+    if (!req) return;
+    req.deferred.fulfill(result);
+  }
+
+  private async open(opts: {
+    defaultTab: MarkdownEmbedRefType;
+    initialTarget?: MarkdownEmbedInitialTarget;
+  }): Promise<MarkdownEmbedResolution> {
+    if (this.currentRequest) {
+      this.currentRequest.deferred.fulfill(undefined);
+    }
+    let deferred = new Deferred<MarkdownEmbedResolution>();
+    this.currentRequest = { ...opts, deferred };
+    try {
+      return await deferred.promise;
+    } finally {
+      if (this.currentRequest?.deferred === deferred) {
+        this.currentRequest = undefined;
+      }
+    }
+  }
+}
+
+declare module '@ember/service' {
+  interface Registry {
+    'markdown-embed-chooser': MarkdownEmbedChooserService;
+  }
+}
diff --git a/packages/host/tests/acceptance/markdown-embed-chooser-test.gts b/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
new file mode 100644
index 00000000000..2caab539958
--- /dev/null
+++ b/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
@@ -0,0 +1,253 @@
+import {
+  click,
+  fillIn,
+  settled,
+  waitFor,
+  waitUntil,
+} from '@ember/test-helpers';
+
+import { module, test } from 'qunit';
+
+import cmContext from '@cardstack/host/lib/codemirror-context';
+
+import {
+  setupAuthEndpoints,
+  setupLocalIndexing,
+  setupOnSave,
+  setupRealmCacheTeardown,
+  setupUserSubscription,
+  setupAcceptanceTestRealm,
+  SYSTEM_CARD_FIXTURE_CONTENTS,
+  testRealmURL,
+  visitOperatorMode,
+  withCachedRealmSetup,
+} from '../helpers';
+import { setupMockMatrix } from '../helpers/mock-matrix';
+import { setupApplicationTest } from '../helpers/setup';
+
+module('Acceptance | markdown embed chooser modal', function (hooks) {
+  setupApplicationTest(hooks);
+  setupLocalIndexing(hooks);
+  setupOnSave(hooks);
+  setupRealmCacheTeardown(hooks);
+
+  let mockMatrixUtils = setupMockMatrix(hooks, {
+    loggedInAs: '@testuser:localhost',
+    activeRealms: [testRealmURL],
+  });
+
+  const noteId = `${testRealmURL}Note/welcome`;
+  const mangoId = `${testRealmURL}Pet/mango`;
+
+  hooks.beforeEach(async function () {
+    let { createAndJoinRoom } = mockMatrixUtils;
+    createAndJoinRoom({
+      sender: '@testuser:localhost',
+      name: 'room-test',
+    });
+    setupUserSubscription();
+    setupAuthEndpoints();
+
+    // Realm contents:
+    // - `note.gts` defines a Note card with a RichMarkdownField body. The
+    //   edit template renders the field, which mounts the CodeMirror editor
+    //   + the toolbar we're testing.
+    // - `pet.gts` is the card we'll embed via the chooser.
+    // - One Note instance ("Welcome") starts empty; one Pet instance
+    //   ("Mango") is the row we pick in the chooser.
+    await withCachedRealmSetup(async () =>
+      setupAcceptanceTestRealm({
+        mockMatrixUtils,
+        contents: {
+          ...SYSTEM_CARD_FIXTURE_CONTENTS,
+          'note.gts': `
+              import { CardDef, Component, contains, field, StringField } from 'https://cardstack.com/base/card-api';
+              import { RichMarkdownField } from 'https://cardstack.com/base/rich-markdown';
+              export class Note extends CardDef {
+                static displayName = 'Note';
+                @field title = contains(StringField);
+                @field body = contains(RichMarkdownField);
+                static isolated = class Isolated extends Component<typeof this> {
+                  <template>
+                    <div data-test-note-isolated>
+                      <h1 data-test-note-title><@fields.title /></h1>
+                      <@fields.body />
+                    </div>
+                  </template>
+                };
+                static edit = class Edit extends Component<typeof this> {
+                  <template>
+                    <div data-test-note-edit>
+                      <h1 data-test-note-title><@fields.title /></h1>
+                      <@fields.body />
+                    </div>
+                  </template>
+                };
+              }
+            `,
+          'pet.gts': `
+              import { CardDef, Component, contains, field, StringField } from 'https://cardstack.com/base/card-api';
+              export class Pet extends CardDef {
+                static displayName = 'Pet';
+                @field name = contains(StringField);
+                @field cardTitle = contains(StringField, {
+                  computeVia: function () {
+                    return this.name;
+                  },
+                });
+                static atom = class Atom extends Component<typeof this> {
+                  <template>
+                    <span data-test-pet-atom>{{@model.name}}</span>
+                  </template>
+                };
+              }
+            `,
+          'Pet/mango.json': {
+            data: {
+              attributes: { name: 'Mango', cardTitle: 'Mango' },
+              meta: {
+                adoptsFrom: { module: '../pet', name: 'Pet' },
+              },
+            },
+          },
+          'Note/welcome.json': {
+            data: {
+              attributes: {
+                title: 'Welcome',
+                cardTitle: 'Welcome',
+                body: { content: '' },
+              },
+              meta: {
+                adoptsFrom: { module: '../note', name: 'Note' },
+              },
+            },
+          },
+        },
+      }),
+    );
+  });
+
+  test('opens via the toolbar Add-embed popover and inserts the picked card as a BFM directive', async function (assert) {
+    await visitOperatorMode({
+      stacks: [
+        [
+          {
+            id: noteId,
+            format: 'isolated',
+          },
+        ],
+      ],
+    });
+
+    // Switch the open card to edit mode so the RichMarkdownField renders
+    // its CodeMirror editor (with the toolbar we are exercising).
+    await click(`[data-test-operator-mode-stack="0"] [data-test-edit-button]`);
+    await waitFor(
+      `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor]`,
+      { timeout: 5000 },
+    );
+    await waitFor('[data-test-toolbar="add-embed"]', { timeout: 5000 });
+
+    // Open the Add-embed popover and pick the Cards menu item.
+    await click('[data-test-toolbar="add-embed"]');
+    assert
+      .dom('[data-test-toolbar-embed-popover]')
+      .exists('popover renders with the two menu items');
+    await click('[data-test-toolbar-embed="card"]');
+
+    // The combined chooser modal opens on the Cards tab.
+    await waitFor('[data-test-markdown-embed-chooser-modal]', {
+      timeout: 5000,
+    });
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab="card"]')
+      .hasAttribute('aria-selected', 'true', 'cards tab is the default');
+
+    // Search for Mango, click the row, wait for the pane to unlock, insert.
+    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="${mangoId}"]`,
+      { timeout: 5000 },
+    );
+    await click(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mangoId}"]`,
+    );
+    await waitFor('[data-test-markdown-embed-preview-cta]:not([disabled])', {
+      timeout: 5000,
+    });
+    await click('[data-test-markdown-embed-preview-cta]');
+
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+    await settled();
+
+    // Read the editor's doc directly: the toolbar dispatched a CM change
+    // and the source now carries the BFM directive at the cursor position.
+    let editorEl = document.querySelector(
+      `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor] .cm-editor`,
+    ) as HTMLElement | null;
+    let docText = editorEl
+      ? cmContext.EditorView.findFromDOM(editorEl)?.state.doc.toString()
+      : undefined;
+    assert.strictEqual(
+      docText,
+      `:card[${mangoId}]`,
+      'source carries the inserted inline atom directive',
+    );
+  });
+
+  test('cursor inside an existing directive swaps the toolbar to the Edit pencil', async function (assert) {
+    // Open the card on the stack, then patch the body content to a pre-
+    // existing :card[...] directive so the cursor lands inside it once the
+    // editor mounts.
+    await visitOperatorMode({
+      stacks: [
+        [
+          {
+            id: noteId,
+            format: 'isolated',
+          },
+        ],
+      ],
+    });
+    await click(`[data-test-operator-mode-stack="0"] [data-test-edit-button]`);
+    await waitFor(
+      `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor]`,
+      { timeout: 5000 },
+    );
+
+    // Inject the directive directly into the CodeMirror view, then drop
+    // the cursor inside it.
+    let editorEl = document.querySelector(
+      `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor] .cm-editor`,
+    ) as HTMLElement | null;
+    let view = editorEl ? cmContext.EditorView.findFromDOM(editorEl) : null;
+    assert.ok(view, 'codemirror view is reachable');
+    view!.focus();
+    view!.dispatch({
+      changes: { from: 0, insert: `:card[${mangoId}]` },
+    });
+    view!.dispatch({ selection: { anchor: 3, head: 3 } });
+
+    await waitFor('[data-test-toolbar="edit-embed"]', { timeout: 5000 });
+    assert
+      .dom('[data-test-toolbar="edit-embed"]')
+      .exists('Edit pencil replaces the Add popover when cursor is inside');
+
+    await click('[data-test-toolbar="edit-embed"]');
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    assert
+      .dom('[data-test-markdown-embed-chooser-current]')
+      .exists('edit modal opens on the current-target tile');
+
+    // Cancel via the X to leave the source untouched.
+    await click('[data-test-close-modal]');
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+  });
+});
diff --git a/packages/host/tests/integration/components/codemirror-editor-test.gts b/packages/host/tests/integration/components/codemirror-editor-test.gts
index eeb14877107..b070e0a3a76 100644
--- a/packages/host/tests/integration/components/codemirror-editor-test.gts
+++ b/packages/host/tests/integration/components/codemirror-editor-test.gts
@@ -1820,4 +1820,82 @@ module('Integration | codemirror-context', function (hooks) {
       delete (globalThis as any).__loadCodeMirror;
     }
   });
+
+  // ── currentRef tracking (BFM directive under cursor) ──
+
+  test('onSelectionChange.currentRef reports the BFM directive under the cursor', async function (assert) {
+    let element = document.createElement('div');
+    document.body.appendChild(element);
+    try {
+      let lastInfo: any = null;
+      let content = 'Inline :card[./mango] then more text';
+      let state = cmContext.createEditorState({
+        content,
+        onDocChange: () => {},
+        onCardTargetsChange: () => {},
+        onOpenCardSearch: () => {},
+        onSelectionChange: (info) => {
+          lastInfo = info;
+        },
+      });
+      let view = new cmContext.EditorView({ state, parent: element });
+
+      let directiveStart = content.indexOf(':card');
+      let directiveEnd = content.indexOf(']') + 1;
+
+      // Inside the directive — currentRef populated.
+      view.dispatch({
+        selection: { anchor: directiveStart + 2, head: directiveStart + 2 },
+      });
+      assert.ok(lastInfo?.currentRef, 'currentRef is set inside the directive');
+      assert.strictEqual(lastInfo.currentRef.refType, 'card');
+      assert.strictEqual(lastInfo.currentRef.url, './mango');
+      assert.strictEqual(lastInfo.currentRef.from, directiveStart);
+      assert.strictEqual(lastInfo.currentRef.to, directiveEnd);
+
+      // Outside the directive — currentRef cleared.
+      view.dispatch({ selection: { anchor: 0, head: 0 } });
+      assert.notOk(
+        lastInfo?.currentRef,
+        'currentRef is undefined outside any directive',
+      );
+
+      view.destroy();
+    } finally {
+      element.remove();
+    }
+  });
+
+  test('currentRef refreshes after a doc edit shifts the range', async function (assert) {
+    let element = document.createElement('div');
+    document.body.appendChild(element);
+    try {
+      let lastInfo: any = null;
+      let state = cmContext.createEditorState({
+        content: ':card[./mango]',
+        onDocChange: () => {},
+        onCardTargetsChange: () => {},
+        onOpenCardSearch: () => {},
+        onSelectionChange: (info) => {
+          lastInfo = info;
+        },
+      });
+      let view = new cmContext.EditorView({ state, parent: element });
+
+      // Prepend text — the directive shifts right by 5 chars.
+      view.dispatch({ changes: { from: 0, to: 0, insert: 'pre: ' } });
+      view.dispatch({ selection: { anchor: 7, head: 7 } });
+
+      assert.ok(lastInfo?.currentRef, 'currentRef detected after the edit');
+      assert.strictEqual(
+        lastInfo.currentRef.from,
+        5,
+        'range start tracks the edit',
+      );
+
+      view.destroy();
+    } finally {
+      element.remove();
+    }
+  });
 });
diff --git a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
new file mode 100644
index 00000000000..3d8b736e2df
--- /dev/null
+++ b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
@@ -0,0 +1,283 @@
+import { precompileTemplate } from '@ember/template-compilation';
+import {
+  type RenderingTestContext,
+  click,
+  fillIn,
+  render,
+  settled,
+  waitFor,
+  waitUntil,
+} from '@ember/test-helpers';
+
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import { getService } from '@universal-ember/test-support';
+import { provide } from 'ember-provide-consume-context';
+
+import { module, test } from 'qunit';
+
+import {
+  baseRealm,
+  CardContextName,
+  GetCardContextName,
+  GetCardCollectionContextName,
+  GetCardsContextName,
+} from '@cardstack/runtime-common';
+
+import MarkdownEmbedChooserModal from '@cardstack/host/components/markdown-embed-chooser/modal';
+import cmContext from '@cardstack/host/lib/codemirror-context';
+import { getCardCollection } from '@cardstack/host/resources/card-collection';
+import { getCard } from '@cardstack/host/resources/card-resource';
+import type LoaderService from '@cardstack/host/services/loader-service';
+import type StoreService from '@cardstack/host/services/store';
+
+import {
+  setupIntegrationTestRealm,
+  setupLocalIndexing,
+  testRealmURL,
+} from '../../helpers';
+import {
+  CardDef,
+  StringField,
+  contains,
+  field,
+  setupBaseRealm,
+} from '../../helpers/base-realm';
+import { setupMockMatrix } from '../../helpers/mock-matrix';
+import { setupRenderingTest } from '../../helpers/setup';
+
+// The mini choosers + card resources consume host context via @consume.
+class HostContextProvider extends GlimmerComponent<{
+  Blocks: { default: [] };
+}> {
+  @provide(GetCardContextName)
+  get getCardFn() {
+    return getCard;
+  }
+  @provide(GetCardsContextName)
+  get getCardsFn() {
+    let store = getService('store') as StoreService;
+    return store.getSearchResource.bind(store);
+  }
+  @provide(GetCardCollectionContextName)
+  get getCardCollectionFn() {
+    return getCardCollection;
+  }
+  @provide(CardContextName)
+  get cardContext() {
+    return {};
+  }
+  <template>
+    {{! template-lint-disable no-yield-only }}
+    {{yield}}
+  </template>
+}
+
+// Tracked content harness so the editor's onUpdate updates the same
+// `@content` arg we read for assertions.
+class ContentHarness {
+  @tracked content = '';
+  set = (text: string) => {
+    this.content = text;
+  };
+}
+
+async function loadCodeMirrorEditor() {
+  let loader = (getService('loader-service') as LoaderService).loader;
+  let mod = (await loader.import(
+    'https://cardstack.com/base/codemirror-editor',
+  )) as { default: unknown };
+  return mod.default as any;
+}
+
+async function renderEditorAndModal(opts: {
+  CodeMirrorEditor: any;
+  harness: ContentHarness;
+}) {
+  // 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;
+  await render(
+    precompileTemplate(
+      `
+      <HostContextProvider>
+        <MarkdownEmbedChooserModal />
+        <div class="editor-sized">
+          <CodeMirrorEditor
+            @content={{harness.content}}
+            @onUpdate={{harness.set}}
+          />
+        </div>
+      </HostContextProvider>
+      <style>
+        .editor-sized {
+          width: 600px;
+          height: 240px;
+        }
+      </style>
+    `,
+      {
+        strictMode: true,
+        scope: () => ({
+          HostContextProvider,
+          MarkdownEmbedChooserModal,
+          CodeMirrorEditor,
+          harness,
+        }),
+      },
+    ),
+  );
+}
+
+module('Integration | codemirror embed toolbar', function (hooks) {
+  setupRenderingTest(hooks);
+  setupBaseRealm(hooks);
+  setupLocalIndexing(hooks);
+
+  let mockMatrixUtils = setupMockMatrix(hooks, {
+    loggedInAs: '@testuser:localhost',
+    activeRealms: [baseRealm.url, testRealmURL],
+    autostart: true,
+  });
+
+  // The base codemirror-editor lazy-loads its host-side CodeMirror context
+  // via `globalThis.__loadCodeMirror`. Wire it to the real context so the
+  // editor mounts (instead of the loading placeholder).
+  hooks.beforeEach(function () {
+    (globalThis as any).__loadCodeMirror = async () => cmContext;
+  });
+  hooks.afterEach(function () {
+    delete (globalThis as any).__loadCodeMirror;
+  });
+
+  let CodeMirrorEditor: any;
+
+  hooks.beforeEach(async function () {
+    CodeMirrorEditor = await loadCodeMirrorEditor();
+  });
+
+  const mango = `${testRealmURL}books/mango`;
+
+  hooks.beforeEach(async function (this: RenderingTestContext) {
+    class Book extends CardDef {
+      static displayName = 'Book';
+      @field title = contains(StringField);
+    }
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      realmURL: testRealmURL,
+      contents: {
+        'book.gts': { Book },
+        'books/mango.json': new Book({ title: 'Mango' }),
+      },
+    });
+    await getService('realm').login(testRealmURL);
+  });
+
+  test('toolbar shows Add-embed by default; popover opens Cards/Files items', async function (assert) {
+    let harness = new ContentHarness();
+    await renderEditorAndModal({ CodeMirrorEditor, harness });
+
+    await waitFor('[data-test-codemirror-editor]', { timeout: 5000 });
+    await waitFor('[data-test-toolbar="add-embed"]', { timeout: 5000 });
+    assert
+      .dom('[data-test-toolbar="add-embed"]')
+      .exists('Add embed lives in the toolbar when no directive is focused');
+    assert
+      .dom('[data-test-toolbar-embed-popover]')
+      .doesNotExist('popover is closed by default');
+
+    await click('[data-test-toolbar="add-embed"]');
+    assert.dom('[data-test-toolbar-embed-popover]').exists();
+    assert
+      .dom('[data-test-toolbar-embed="card"]')
+      .hasText('Add a card', 'first menu item targets the Cards tab');
+    assert
+      .dom('[data-test-toolbar-embed="file"]')
+      .hasText('Add a file', 'second menu item targets the Files tab');
+  });
+
+  test('picking a card from the popover inserts `:card[URL]` at the cursor', async function (assert) {
+    let harness = new ContentHarness();
+    await renderEditorAndModal({ CodeMirrorEditor, harness });
+
+    await waitFor('[data-test-toolbar="add-embed"]', { timeout: 5000 });
+    await click('[data-test-toolbar="add-embed"]');
+    await click('[data-test-toolbar-embed="card"]');
+
+    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]');
+
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+    await settled();
+    assert.strictEqual(
+      harness.content,
+      `:card[${mango}]`,
+      'editor content carries the inserted BFM directive',
+    );
+  });
+
+  test('cursor over a directive swaps the toolbar to Edit; Remove deletes the ref', async function (assert) {
+    let harness = new ContentHarness();
+    harness.content = `:card[${mango}]`;
+    await renderEditorAndModal({ CodeMirrorEditor, harness });
+
+    await waitFor('[data-test-codemirror-editor] .cm-content', {
+      timeout: 5000,
+    });
+
+    // Drop the cursor inside the directive by dispatching against the
+    // CodeMirror view. `EditorView.findFromDOM` walks up from any node
+    // under the editor; the cmContext exposes the constructor.
+    let editor = document.querySelector(
+      '[data-test-codemirror-editor] .cm-editor',
+    ) as HTMLElement | null;
+    let view = editor ? cmContext.EditorView.findFromDOM(editor) : null;
+    view?.focus();
+    view?.dispatch({ selection: { anchor: 3, head: 3 } });
+
+    await waitFor('[data-test-toolbar="edit-embed"]', { timeout: 5000 });
+    assert
+      .dom('[data-test-toolbar="edit-embed"]')
+      .exists(
+        'Edit pencil replaces the Add popover when the cursor is inside a directive',
+      );
+
+    await click('[data-test-toolbar="edit-embed"]');
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    assert
+      .dom('[data-test-markdown-embed-chooser-current]')
+      .exists('edit modal opens with the current-target tile');
+
+    await click('[data-test-markdown-embed-chooser-remove]');
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+    await settled();
+    assert.strictEqual(
+      harness.content,
+      '',
+      'Remove deletes the directive from the source',
+    );
+  });
+});
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
new file mode 100644
index 00000000000..8a8bad747de
--- /dev/null
+++ b/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
@@ -0,0 +1,353 @@
+import {
+  type RenderingTestContext,
+  click,
+  fillIn,
+  render,
+  waitFor,
+  waitUntil,
+} from '@ember/test-helpers';
+
+import GlimmerComponent from '@glimmer/component';
+
+import { getService } from '@universal-ember/test-support';
+import { provide } from 'ember-provide-consume-context';
+
+import { module, test } from 'qunit';
+
+import {
+  baseRealm,
+  CardContextName,
+  GetCardContextName,
+  GetCardCollectionContextName,
+  GetCardsContextName,
+} from '@cardstack/runtime-common';
+
+import MarkdownEmbedChooserModal from '@cardstack/host/components/markdown-embed-chooser/modal';
+import { getCardCollection } from '@cardstack/host/resources/card-collection';
+import { getCard } from '@cardstack/host/resources/card-resource';
+import type MarkdownEmbedChooserService from '@cardstack/host/services/markdown-embed-chooser';
+import type StoreService from '@cardstack/host/services/store';
+
+import {
+  setupIntegrationTestRealm,
+  setupLocalIndexing,
+  testRealmURL,
+} from '../../helpers';
+import {
+  CardDef,
+  StringField,
+  contains,
+  field,
+  setupBaseRealm,
+} from '../../helpers/base-realm';
+import { setupMockMatrix } from '../../helpers/mock-matrix';
+import { setupRenderingTest } from '../../helpers/setup';
+
+// The mini choosers consume host context via @consume — provide it here so the
+// modal renders standalone in this rendering test.
+class HostContextProvider extends GlimmerComponent<{
+  Blocks: { default: [] };
+}> {
+  @provide(GetCardContextName)
+  get getCardFn() {
+    return getCard;
+  }
+  @provide(GetCardsContextName)
+  get getCardsFn() {
+    let store = getService('store') as StoreService;
+    return store.getSearchResource.bind(store);
+  }
+  @provide(GetCardCollectionContextName)
+  get getCardCollectionFn() {
+    return getCardCollection;
+  }
+  @provide(CardContextName)
+  get cardContext() {
+    return {};
+  }
+  <template>
+    {{! template-lint-disable no-yield-only }}
+    {{yield}}
+  </template>
+}
+
+module('Integration | markdown-embed-chooser-modal', function (hooks) {
+  setupRenderingTest(hooks);
+  setupBaseRealm(hooks);
+  setupLocalIndexing(hooks);
+
+  let mockMatrixUtils = setupMockMatrix(hooks, {
+    loggedInAs: '@testuser:localhost',
+    activeRealms: [baseRealm.url, testRealmURL],
+    autostart: true,
+  });
+
+  const mango = `${testRealmURL}books/mango`;
+
+  hooks.beforeEach(async function (this: RenderingTestContext) {
+    class Book extends CardDef {
+      static displayName = 'Book';
+      @field title = contains(StringField);
+    }
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      realmURL: testRealmURL,
+      contents: {
+        'book.gts': { Book },
+        'books/mango.json': new Book({ title: 'Mango' }),
+        'books/vincent.json': new Book({ title: 'Vincent' }),
+        'notes/hello.txt': 'hello',
+      },
+    });
+    await getService('realm').login(testRealmURL);
+  });
+
+  test('opens on the default tab and mounts both tabpanels', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    assert
+      .dom('[data-test-markdown-embed-chooser-modal]')
+      .doesNotExist('the modal is closed by default');
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.chooseCardOrFile({ defaultTab: 'card' });
+
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab="card"]')
+      .hasAttribute('aria-selected', 'true', 'cards tab is active');
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab="file"]')
+      .hasAttribute('aria-selected', 'false', 'files tab is inactive');
+    // Both panels stay in the DOM so per-tab state survives a switch.
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab-panel="card"]')
+      .exists('card tab-panel is mounted');
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab-panel="file"]')
+      .exists('file tab-panel is mounted even while inactive');
+
+    // Resolve to clean up the pending promise.
+    svc.resolve(undefined);
+    await pending;
+  });
+
+  test('the cards tab search query survives a switch to files and back', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.chooseCardOrFile({ defaultTab: 'card' });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // Type into the cards search bar (scoped to the card tab-panel).
+    await fillIn(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-search-field]',
+      'Vinc',
+    );
+
+    await click('[data-test-markdown-embed-chooser-tab="file"]');
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab="file"]')
+      .hasAttribute('aria-selected', 'true');
+
+    await click('[data-test-markdown-embed-chooser-tab="card"]');
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-search-field]',
+      )
+      .hasValue('Vinc', 'card-tab search query survived the round-trip');
+
+    svc.resolve(undefined);
+    await pending;
+  });
+
+  test('closing the modal resolves the deferred with undefined', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.chooseCardOrFile();
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    await click('[data-test-close-modal]');
+    let result = await pending;
+    assert.strictEqual(result, undefined, 'cancelling resolves with undefined');
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+  });
+
+  test('edit mode preloads the matching tab in current view', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.editEmbed({
+      refType: 'card',
+      url: mango,
+      sizeSpec: 'embedded',
+    });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // Cards tab opens in 'current' mode (the placed target tile, not the
+    // chooser); the files tab still shows its chooser per Zeplin 08B.
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-chooser-current]',
+      )
+      .exists('cards tab shows the current-target tile');
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="file"] [data-test-mini-file-chooser]',
+      )
+      .exists('files tab still mounts its chooser');
+
+    // CTA seeds at DONE (initial preload, nothing edited yet).
+    await waitFor('[data-test-markdown-embed-preview-cta]:not([disabled])', {
+      timeout: 5000,
+    });
+    assert
+      .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');
+
+    svc.resolve(undefined);
+    await pending;
+  });
+
+  test('Remove resolves the deferred with { remove: true }', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.editEmbed({
+      refType: 'card',
+      url: mango,
+      sizeSpec: 'embedded',
+    });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    await click('[data-test-markdown-embed-chooser-remove]');
+    let result = await pending;
+    assert.deepEqual(
+      result,
+      { remove: true },
+      'Remove resolves the deferred with the remove sentinel',
+    );
+  });
+
+  test('Replace swaps the current-target tile back to the mini chooser', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.editEmbed({
+      refType: 'card',
+      url: mango,
+      sizeSpec: 'embedded',
+    });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    await click('[data-test-markdown-embed-chooser-replace]');
+
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-chooser-current]',
+      )
+      .doesNotExist('current-target tile is hidden after Replace');
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-mini-card-chooser]',
+      )
+      .exists('mini chooser is exposed for picking a new card');
+
+    svc.resolve(undefined);
+    await pending;
+  });
+
+  test('picking a card resolves the deferred with the serialized BFM', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.chooseCardOrFile({ defaultTab: 'card' });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // Search for the seeded card and click its row. SearchResultSection
+    // renders rows under [data-test-search-result] in the mini variant.
+    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}"]`,
+    );
+
+    // Pane unlocks once the target loads.
+    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[${mango}]` },
+      'resolves with the serialized BFM directive for the picked card',
+    );
+  });
+});
diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 8e16f658c4c..858f2d1e034 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -6,6 +6,7 @@ import {
   extractCardReferenceUrls,
   extractFileReferenceUrls,
   extractBfmReferences,
+  extractBfmRefRanges,
   bfmRefFormatAndSize,
   bfmCardReferenceExtensions,
   bfmExtensionsForKeyword,
@@ -1253,4 +1254,70 @@ module('Unit | bfm-card-references', function () {
       assert.strictEqual(serializeBfmRef('card', ''), '');
     });
   });
+
+  module('extractBfmRefRanges', function () {
+    test('returns source-byte ranges for inline and block refs', function (assert) {
+      let markdown = 'Inline :card[./mango] then\n::file[./photo.jpg]\n';
+      let ranges = extractBfmRefRanges(markdown);
+      assert.strictEqual(ranges.length, 2);
+
+      let inline = ranges[0];
+      assert.strictEqual(inline.kind, 'inline');
+      assert.strictEqual(inline.refType, 'card');
+      assert.strictEqual(inline.url, './mango');
+      assert.strictEqual(
+        markdown.slice(inline.from, inline.to),
+        ':card[./mango]',
+        'inline range round-trips through markdown.slice',
+      );
+
+      let block = ranges[1];
+      assert.strictEqual(block.kind, 'block');
+      assert.strictEqual(block.refType, 'file');
+      assert.strictEqual(block.url, './photo.jpg');
+      assert.strictEqual(
+        markdown.slice(block.from, block.to),
+        '::file[./photo.jpg]',
+        'block range round-trips through markdown.slice',
+      );
+    });
+
+    test('captures the size specifier when present', function (assert) {
+      let markdown = '::card[./mango | tall-tile]';
+      let [range] = extractBfmRefRanges(markdown);
+      assert.strictEqual(range.url, './mango');
+      assert.strictEqual(range.sizeSpec, 'tall-tile');
+      assert.strictEqual(markdown.slice(range.from, range.to), markdown);
+    });
+
+    test('skips refs inside fenced and inline code', function (assert) {
+      let markdown = [
+        '```',
+        '::card[./inside-fence]',
+        '```',
+        'See `:card[./inline-code]` and :card[./real] for real.',
+      ].join('\n');
+      let ranges = extractBfmRefRanges(markdown);
+      assert.strictEqual(ranges.length, 1, 'only the un-coded ref is returned');
+      assert.strictEqual(ranges[0].url, './real');
+    });
+
+    test('emits one range per site (no deduplication)', function (assert) {
+      let markdown = ':card[./mango] then :card[./mango]';
+      let ranges = extractBfmRefRanges(markdown);
+      assert.strictEqual(ranges.length, 2, 'both sites are surfaced');
+      assert.notStrictEqual(ranges[0].from, ranges[1].from);
+    });
+
+    test('sorts by document order', function (assert) {
+      let markdown = [':card[./first] inline', '', '::card[./second]'].join(
+        '\n',
+      );
+      let ranges = extractBfmRefRanges(markdown);
+      assert.deepEqual(
+        ranges.map((r) => r.url),
+        ['./first', './second'],
+      );
+    });
+  });
 });
diff --git a/packages/runtime-common/bfm-card-references.ts b/packages/runtime-common/bfm-card-references.ts
index f1b11d54744..20b1df48941 100644
--- a/packages/runtime-common/bfm-card-references.ts
+++ b/packages/runtime-common/bfm-card-references.ts
@@ -328,6 +328,152 @@ export function extractBfmReferences(
   return refs;
 }
 
+// ── Markdown embed chooser bridge ──
+//
+// Lets the base-realm markdown editor (in `packages/base/`) open the host-
+// side combined chooser modal without importing host services directly. The
+// host modal registers itself on `globalThis` at mount time; runtime-common
+// exposes the typed accessors below. Mirrors the `chooseCard` / `chooseFile`
+// pattern used by other host-side modals.
+
+export interface MarkdownEmbedResult {
+  refType: 'card' | 'file';
+  url: string;
+  bfm: string;
+}
+
+export type MarkdownEmbedResolution =
+  | MarkdownEmbedResult
+  | { remove: true }
+  | undefined;
+
+export interface MarkdownEmbedInitialTarget {
+  refType: 'card' | 'file';
+  url: string;
+  // Either a pre-parsed `BfmSizeSpec` or the raw specifier text after `|`.
+  sizeSpec?: BfmSizeSpec | string;
+}
+
+export interface MarkdownEmbedChooser {
+  chooseCardOrFile(opts: {
+    defaultTab?: 'card' | 'file';
+  }): Promise<MarkdownEmbedResolution>;
+  editEmbed(
+    target: MarkdownEmbedInitialTarget,
+  ): Promise<MarkdownEmbedResolution>;
+}
+
+const MARKDOWN_EMBED_CHOOSER_KEY = '_CARDSTACK_MARKDOWN_EMBED_CHOOSER';
+
+export async function chooseMarkdownEmbed(
+  opts: { defaultTab?: 'card' | 'file' } = {},
+): Promise<MarkdownEmbedResolution> {
+  let here = globalThis as any;
+  let chooser: MarkdownEmbedChooser | undefined =
+    here[MARKDOWN_EMBED_CHOOSER_KEY];
+  if (!chooser) {
+    throw new Error(
+      `no cardstack markdown-embed chooser is available in this environment`,
+    );
+  }
+  return chooser.chooseCardOrFile(opts);
+}
+
+export async function editMarkdownEmbed(
+  target: MarkdownEmbedInitialTarget,
+): Promise<MarkdownEmbedResolution> {
+  let here = globalThis as any;
+  let chooser: MarkdownEmbedChooser | undefined =
+    here[MARKDOWN_EMBED_CHOOSER_KEY];
+  if (!chooser) {
+    throw new Error(
+      `no cardstack markdown-embed chooser is available in this environment`,
+    );
+  }
+  return chooser.editEmbed(target);
+}
+
+export interface BfmRefRange {
+  kind: 'inline' | 'block';
+  // Half-open byte range into the original markdown string: `markdown.slice(
+  // from, to)` reproduces the directive verbatim. Suitable for a CodeMirror
+  // dispatch that replaces or deletes the directive in place.
+  from: number;
+  to: number;
+  refType: string;
+  // Unresolved URL as written between `[` and `]` — callers resolve against
+  // a base URL when they need the canonical form.
+  url: string;
+  // Raw size specifier after `|` (e.g. `'embedded'`, `'tall-tile'`,
+  // `'w:400 h:200'`). Undefined when the directive has no `|` segment.
+  sizeSpec?: string;
+}
+
+/**
+ * Locates every BFM reference site in `markdown` and returns its source-byte
+ * range, refType, URL, and size specifier (verbatim — no URL resolution).
+ *
+ * Differs from `extractBfmReferences` in two ways: indices are into the
+ * ORIGINAL markdown (not a code-stripped copy), and matches are not
+ * deduplicated — every site is its own range. References inside fenced code
+ * blocks and inline code are skipped.
+ *
+ * Intended for editor-side tooling — cursor-over-ref detection, in-place
+ * replacement, deletion — where every directive needs its own `[from, to]`.
+ */
+export function extractBfmRefRanges(
+  markdown: string,
+  keywords: string[] = ['card', 'file'],
+): BfmRefRange[] {
+  // Collect code regions to skip. Sorted spans in the original markdown.
+  let codeRegions: Array<[number, number]> = [];
+  for (let m of markdown.matchAll(FENCED_CODE_RE)) {
+    codeRegions.push([m.index!, m.index! + m[0].length]);
+  }
+  for (let m of markdown.matchAll(INLINE_CODE_RE)) {
+    codeRegions.push([m.index!, m.index! + m[0].length]);
+  }
+  codeRegions.sort((a, b) => a[0] - b[0]);
+  let isInCode = (pos: number) =>
+    codeRegions.some(([s, e]) => pos >= s && pos < e);
+
+  let ranges: BfmRefRange[] = [];
+
+  for (let keyword of keywords) {
+    let escaped = escapeRegExp(keyword);
+    let blockRe = new RegExp(`^::${escaped}\\[([^\\]]+)\\]`, 'gm');
+    let inlineRe = new RegExp(`(?<!:):${escaped}\\[([^\\]]+)\\]`, 'g');
+
+    for (let match of markdown.matchAll(blockRe)) {
+      if (isInCode(match.index!)) continue;
+      let { url, specifier } = splitBfmContent(match[1]);
+      ranges.push({
+        kind: 'block',
+        from: match.index!,
+        to: match.index! + match[0].length,
+        refType: keyword,
+        url,
+        sizeSpec: specifier,
+      });
+    }
+    for (let match of markdown.matchAll(inlineRe)) {
+      if (isInCode(match.index!)) continue;
+      let { url, specifier } = splitBfmContent(match[1]);
+      ranges.push({
+        kind: 'inline',
+        from: match.index!,
+        to: match.index! + match[0].length,
+        refType: keyword,
+        url,
+        sizeSpec: specifier,
+      });
+    }
+  }
+
+  ranges.sort((a, b) => a.from - b.from);
+  return ranges;
+}
+
 /**
  * Convenience wrapper that extracts only `:card[URL]` / `::card[URL]`
  * references and returns just the resolved URL strings.