diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts
index 273c39401e..312cd7d7e5 100644
--- a/packages/base/card-api.gts
+++ b/packages/base/card-api.gts
@@ -16,7 +16,6 @@ import { getLinksToManyComponent } from './links-to-many-component';
 import {
   assertIsSerializerName,
   baseRef,
-  baseRealm,
   CardContextName,
   CardError,
   CodeRef,
@@ -32,12 +31,12 @@ import {
   getSerializer,
   humanReadable,
   identifyCard,
-  normalizeCodeRef,
   isBaseInstance,
   isCardError,
   isCardInstance as _isCardInstance,
   isCardResource,
   isFileMetaResource,
+  isFileDef,
   isField,
   isFieldInstance,
   isRelationship,
@@ -170,6 +169,7 @@ export {
   getFields,
   isCard,
   isField,
+  isFileDef,
   localId,
   meta,
   primitive,
@@ -336,28 +336,6 @@ export function instanceOf(instance: BaseDef, clazz: typeof BaseDef): boolean {
   return false;
 }
 
-export function isFileDefConstructor(card: typeof BaseDef): boolean {
-  let baseFileDefRef = {
-    module: `${baseRealm.url}file-api`,
-    name: 'FileDef',
-  };
-  let current: typeof BaseDef | undefined = card;
-  while (current) {
-    let ref = identifyCard(current);
-    if (ref) {
-      let normalized = normalizeCodeRef(ref);
-      if (
-        normalized.module === baseFileDefRef.module &&
-        normalized.name === baseFileDefRef.name
-      ) {
-        return true;
-      }
-    }
-    current = getAncestor(current) as typeof BaseDef | undefined;
-  }
-  return false;
-}
-
 class Logger {
   private promises: Promise<any>[] = [];
 
@@ -1090,7 +1068,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
     visited: Set<string>,
     opts?: SerializeOpts,
   ) {
-    let relationshipType = isFileDefConstructor(this.card as typeof BaseDef)
+    let relationshipType = isFileDef(this.card)
       ? FileMetaResourceType
       : CardResourceType;
     if (isNotLoadedValue(value)) {
@@ -1100,6 +1078,10 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
             links: {
               self: makeRelativeURL(value.reference, opts),
             },
+            data: {
+              type: relationshipType,
+              id: makeRelativeURL(value.reference, opts),
+            },
           },
         },
       };
@@ -1113,7 +1095,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
         },
       };
     }
-    if (isFileDefConstructor(this.card as typeof BaseDef) && !value.id) {
+    if (isFileDef(this.card) && !value.id) {
       throw new Error(
         `linksTo field '${this.name}' cannot serialize a FileDef without an id`,
       );
@@ -1269,7 +1251,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
       if (isNotLoadedValue(value)) {
         return value;
       }
-      if (isFileDefConstructor(this.card as typeof BaseDef) && !value.id) {
+      if (isFileDef(this.card) && !value.id) {
         throw new Error(
           `field validation error: the linksTo field '${this.name}' cannot reference a FileDef without an id`,
         );
@@ -1313,14 +1295,13 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
       let innerModel = model.field(fieldName);
       return innerModel as unknown as Box<CardDef | null>;
     };
-    let isFileDef = isFileDefConstructor(linksToField.card as typeof BaseDef);
+    let isFileDefField = isFileDef(linksToField.card);
     function shouldRenderEditor(
       format: Format | undefined,
       defaultFormat: Format,
       isComputed: boolean,
-      isFileDef: boolean,
     ) {
-      return (format ?? defaultFormat) === 'edit' && !isComputed && !isFileDef;
+      return (format ?? defaultFormat) === 'edit' && !isComputed;
     }
     function getChildFormat(
       format: Format | undefined,
@@ -1354,9 +1335,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
         <CardCrudFunctionsConsumer as |cardCrudFunctions|>
           <DefaultFormatsConsumer as |defaultFormats|>
             {{#if
-              (shouldRenderEditor
-                @format defaultFormats.cardDef isComputed isFileDef
-              )
+              (shouldRenderEditor @format defaultFormats.cardDef isComputed)
             }}
               <LinksToEditor
                 @model={{(getInnerModel)}}
@@ -1372,7 +1351,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
                     @format
                     defaultFormats.cardDef
                     model
-                    isFileDef
+                    isFileDefField
                   }}
                   @displayContainer={{@displayContainer}}
                   ...attributes
@@ -1583,7 +1562,7 @@ class LinksToMany<FieldT extends LinkableDefConstructor>
       throw new Error(`Expected array for field value ${this.name}`);
     }
 
-    let relationshipType = isFileDefConstructor(this.card as typeof BaseDef)
+    let relationshipType = isFileDef(this.card)
       ? FileMetaResourceType
       : CardResourceType;
     let relationships: Record<string, Relationship> = {};
@@ -1606,7 +1585,7 @@ class LinksToMany<FieldT extends LinkableDefConstructor>
         };
         return;
       }
-      if (isFileDefConstructor(this.card as typeof BaseDef) && !value.id) {
+      if (isFileDef(this.card) && !value.id) {
         throw new Error(
           `linksToMany field '${this.name}' cannot serialize a FileDef without an id`,
         );
@@ -1818,7 +1797,7 @@ class LinksToMany<FieldT extends LinkableDefConstructor>
       if (
         !isNotLoadedValue(value) &&
         value != null &&
-        isFileDefConstructor(expectedCard as typeof BaseDef) &&
+        isFileDef(expectedCard) &&
         !value.id
       ) {
         throw new Error(
@@ -2773,7 +2752,7 @@ function lazilyLoadLink(
     ),
   );
   (async () => {
-    let isFileLink = isFileDefConstructor(field.card as typeof BaseDef);
+    let isFileLink = isFileDef(field.card);
     try {
       let fieldValue: CardDef | FileDef;
       if (isFileLink) {
@@ -2840,6 +2819,11 @@ function lazilyLoadLink(
         isFileLink || reference.endsWith('.json')
           ? reference
           : `${reference}.json`;
+      if (isMissingFile) {
+        console.warn(
+          `[linksTo missing file] field=${field.name} reference=${reference} referenceForMissingFile=${referenceForMissingFile} isFileLink=${isFileLink}`,
+        );
+      }
       let payloadError: {
         title: string;
         status: number;
@@ -2859,6 +2843,12 @@ function lazilyLoadLink(
       if (isCardError(error) && error.deps?.length) {
         payloadError.deps = [...new Set(error.deps)];
       }
+      if (isMissingFile) {
+        let missingDep = isFileLink ? reference : referenceForMissingFile;
+        payloadError.deps = [
+          ...new Set([...(payloadError.deps ?? []), missingDep]),
+        ];
+      }
       let payload = JSON.stringify({
         type: 'error',
         error: payloadError,
diff --git a/packages/base/links-to-editor.gts b/packages/base/links-to-editor.gts
index d451f07b60..3a70f46a2d 100644
--- a/packages/base/links-to-editor.gts
+++ b/packages/base/links-to-editor.gts
@@ -10,16 +10,17 @@ import {
   getBoxComponent,
 } from './field-component';
 import {
-  type CardDef,
   type BaseDef,
   type Box,
   type Field,
   type CardContext,
   type LinkableDefConstructor,
   CreateCardFn,
+  isFileDef,
 } from './card-api';
 import {
   chooseCard,
+  chooseFile,
   baseCardRef,
   identifyCard,
   CardContextName,
@@ -37,7 +38,7 @@ import { hash } from '@ember/helper';
 interface Signature {
   Element: HTMLElement;
   Args: {
-    model: Box<CardDef | null>;
+    model: Box<BaseDef | null>;
     field: Field<LinkableDefConstructor>;
     typeConstraint?: ResolvedCodeRef;
     createCard?: CreateCardFn;
@@ -166,6 +167,14 @@ export class LinksToEditor extends GlimmerComponent<Signature> {
   }
 
   private chooseCard = restartableTask(async () => {
+    if (isFileDef(this.args.field.card)) {
+      let file = await chooseFile();
+      if (file) {
+        this.args.model.value = file;
+      }
+      return;
+    }
+
     let type = identifyCard(this.args.field.card) ?? baseCardRef;
     if (this.args.typeConstraint) {
       type = await getNarrowestType(this.args.typeConstraint, type, myLoader());
diff --git a/packages/base/links-to-many-component.gts b/packages/base/links-to-many-component.gts
index 2a6b173fd2..d33e5bc920 100644
--- a/packages/base/links-to-many-component.gts
+++ b/packages/base/links-to-many-component.gts
@@ -13,7 +13,7 @@ import {
   type LinkableDefConstructor,
   CreateCardFn,
   CardCrudFunctions,
-  isFileDefConstructor,
+  isFileDef,
 } from './card-api';
 import {
   BoxComponentSignature,
@@ -482,9 +482,8 @@ function shouldRenderEditor(
   format: Format | undefined,
   defaultFormat: Format,
   isComputed: boolean,
-  isFileDef: boolean,
 ) {
-  return (format ?? defaultFormat) === 'edit' && !isComputed && !isFileDef;
+  return (format ?? defaultFormat) === 'edit' && !isComputed;
 }
 const componentCache = initSharedState(
   'linksToManyComponentCache',
@@ -515,15 +514,11 @@ export function getLinksToManyComponent({
       getBoxComponent(cardTypeFor(field, child), child, field),
     ); // Wrap the the components in a function so that the template is reactive to changes in the model (this is essentially a helper)
   let isComputed = !!field.computeVia || !!field.queryDefinition;
-  let isFileDef = isFileDefConstructor(field.card as typeof BaseDef);
+  let isFileDefField = isFileDef(field.card);
   let linksToManyComponent = class LinksToManyComponent extends GlimmerComponent<BoxComponentSignature> {
     <template>
       <DefaultFormatsConsumer as |defaultFormats|>
-        {{#if
-          (shouldRenderEditor
-            @format defaultFormats.cardDef isComputed isFileDef
-          )
-        }}
+        {{#if (shouldRenderEditor @format defaultFormats.cardDef isComputed)}}
           <LinksToManyEditor
             @model={{model}}
             @arrayField={{arrayField}}
@@ -559,7 +554,7 @@ export function getLinksToManyComponent({
                     @format={{getPluralChildFormat
                       effectiveFormat
                       model
-                      isFileDef
+                      isFileDefField
                     }}
                     @displayContainer={{@displayContainer}}
                     class='linksToMany-item'
diff --git a/packages/host/app/components/card-prerender.gts b/packages/host/app/components/card-prerender.gts
index 0572fc3195..79498ac8aa 100644
--- a/packages/host/app/components/card-prerender.gts
+++ b/packages/host/app/components/card-prerender.gts
@@ -380,6 +380,8 @@ export default class CardPrerender extends Component {
       renderOptions?: RenderRouteOptions;
     }): Promise<FileExtractResponse> => {
       this.#nonce++;
+      this.localIndexer.renderError = undefined;
+      this.#renderErrorPayload = undefined;
       let shouldClearCache = this.#consumeClearCacheForRender(
         Boolean(renderOptions?.clearCache),
       );
diff --git a/packages/host/app/components/operator-mode/choose-file-modal.gts b/packages/host/app/components/operator-mode/choose-file-modal.gts
index 8374016328..231a99086a 100644
--- a/packages/host/app/components/operator-mode/choose-file-modal.gts
+++ b/packages/host/app/components/operator-mode/choose-file-modal.gts
@@ -20,14 +20,14 @@ import {
   Deferred,
   RealmPaths,
   type LocalPath,
+  isCardErrorJSONAPI,
 } from '@cardstack/runtime-common';
 
 import ModalContainer from '@cardstack/host/components/modal-container';
 
-import type MatrixService from '@cardstack/host/services/matrix-service';
 import type OperatorModeStateService from '@cardstack/host/services/operator-mode-state-service';
-
 import type RealmService from '@cardstack/host/services/realm';
+import type StoreService from '@cardstack/host/services/store';
 
 import type { FileDef } from 'https://cardstack.com/base/file-api';
 
@@ -44,7 +44,7 @@ export default class ChooseFileModal extends Component<Signature> {
 
   @service private declare operatorModeStateService: OperatorModeStateService;
   @service private declare realm: RealmService;
-  @service private declare matrixService: MatrixService;
+  @service private declare store: StoreService;
 
   constructor(owner: Owner, args: Signature['Args']) {
     super(owner, args);
@@ -72,13 +72,15 @@ export default class ChooseFileModal extends Component<Signature> {
   }
 
   @action
-  private pick(path: LocalPath | undefined) {
+  private async pick(path: LocalPath | undefined) {
     if (this.deferred && this.selectedRealm && path) {
       let fileURL = new RealmPaths(this.selectedRealm.url).fileURL(path);
-      let file = this.matrixService.fileAPI.createFileDef({
-        sourceUrl: fileURL.toString(),
-        name: fileURL.toString().split('/').pop()!,
-      });
+      let file = await this.store.getFileMeta<FileDef>(fileURL.href);
+      if (isCardErrorJSONAPI(file)) {
+        throw new Error(
+          `choose-file-modal: failed to load file meta for ${fileURL.href}`,
+        );
+      }
       this.deferred.fulfill(file);
     }
 
diff --git a/packages/host/app/services/store.ts b/packages/host/app/services/store.ts
index 319c8b2000..36f534e1bf 100644
--- a/packages/host/app/services/store.ts
+++ b/packages/host/app/services/store.ts
@@ -52,6 +52,7 @@ import {
 
 import type { CardDef, BaseDef } from 'https://cardstack.com/base/card-api';
 import type * as CardAPI from 'https://cardstack.com/base/card-api';
+import type { FileDef } from 'https://cardstack.com/base/file-api';
 
 import type { RealmEventContent } from 'https://cardstack.com/base/matrix-event';
 
@@ -377,6 +378,31 @@ export default class StoreService extends Service implements StoreInterface {
     return await this.getInstance<T>({ idOrDoc: id });
   }
 
+  async getFileMeta<T extends FileDef>(
+    url: string,
+  ): Promise<T | CardErrorJSONAPI> {
+    return await this.withTestWaiters(async () => {
+      try {
+        let fileMetaDoc = await this.store.loadFileMetaDocument(url);
+        if (isCardError(fileMetaDoc)) {
+          throw fileMetaDoc;
+        }
+        let api = await this.cardService.getAPI();
+        let fileInstance = await api.createFromSerialized(
+          fileMetaDoc.data,
+          fileMetaDoc,
+          fileMetaDoc.data.id ? new URL(fileMetaDoc.data.id) : new URL(url),
+          { store: this.store },
+        );
+        this.setIdentityContext(fileInstance as unknown as CardDef);
+        return fileInstance as unknown as T;
+      } catch (error: any) {
+        let errorResponse = processCardError(url, error);
+        return errorResponse.errors[0];
+      }
+    });
+  }
+
   // Bypass cached state and fetch from source of truth
   async getWithoutCache<T extends CardDef>(
     id: string,
diff --git a/packages/host/app/utils/render-error.ts b/packages/host/app/utils/render-error.ts
index bf1893f39f..2b63f63bb6 100644
--- a/packages/host/app/utils/render-error.ts
+++ b/packages/host/app/utils/render-error.ts
@@ -124,11 +124,7 @@ function applyAuthMessageOverrides(renderError: RenderError): RenderError {
 function extractMissingRefFromMessage(message: string): string | undefined {
   let match = /^missing file (.+?)(?: not found)?$/i.exec(message.trim());
   if (match?.[1]) {
-    let ref = match[1].trim();
-    if (!ref.endsWith('.json')) {
-      ref = `${ref}.json`;
-    }
-    return ref;
+    return match[1].trim();
   }
   return undefined;
 }
diff --git a/packages/host/tests/acceptance/interact-submode-test.gts b/packages/host/tests/acceptance/interact-submode-test.gts
index f089f925eb..b26e0a6d50 100644
--- a/packages/host/tests/acceptance/interact-submode-test.gts
+++ b/packages/host/tests/acceptance/interact-submode-test.gts
@@ -6,6 +6,7 @@ import {
   typeIn,
   triggerKeyEvent,
   settled,
+  waitFor,
 } from '@ember/test-helpers';
 
 import { triggerEvent } from '@ember/test-helpers';
@@ -511,7 +512,7 @@ module('Acceptance | interact submode tests', function (hooks) {
     });
 
     test('clicking a linked file opens it as a new isolated stack item', async function (assert) {
-      let fileId = `${testRealmURL}FileLinkCard/notes.txt`;
+      let fileId = `${testRealmURL}FileLinkCard/notes.md`;
       await visitOperatorMode({
         stacks: [
           [
@@ -549,6 +550,55 @@ module('Acceptance | interact submode tests', function (hooks) {
       });
     });
 
+    test('can link a file via the chooser and index the update', async function (assert) {
+      let cardId = `${testRealmURL}FileLinkCard/empty`;
+      await visitOperatorMode({
+        stacks: [
+          [
+            {
+              id: cardId,
+              format: 'edit',
+            },
+          ],
+        ],
+      });
+
+      let messageService = getService('message-service');
+      let receivedEventDeferred = new Deferred<IncrementalIndexEventContent>();
+      messageService.listenerCallbacks.get(testRealmURL)!.push((ev) => {
+        if (
+          ev.eventName === 'index' &&
+          ev.indexType === 'incremental-index-initiation'
+        ) {
+          return; // ignore the index initiation event
+        }
+        if (ev.eventName === 'index' && ev.indexType === 'incremental') {
+          receivedEventDeferred.fulfill(ev as IncrementalIndexEventContent);
+        }
+      });
+
+      await click(
+        `[data-test-links-to-editor="attachment"] [data-test-add-new="attachment"]`,
+      );
+      await waitFor('[data-test-file="README.md"]');
+      await click('[data-test-file="README.md"]');
+      await click('[data-test-choose-file-modal-add-button]');
+
+      await click('[data-test-edit-button]');
+
+      assert
+        .dom(
+          `[data-test-stack-card="${cardId}"] [data-test-file-link-attachment]`,
+        )
+        .includesText('Hello World', 'linked file is rendered');
+
+      let indexEvent = await receivedEventDeferred.promise;
+      assert.ok(
+        indexEvent.invalidations.includes(cardId),
+        'indexing invalidates the edited card',
+      );
+    });
+
     test('can save mutated card without having opened in stack', async function (assert) {
       await visitOperatorMode({
         stacks: [
diff --git a/packages/host/tests/helpers/interact-submode-setup.gts b/packages/host/tests/helpers/interact-submode-setup.gts
index 6cc37ea5f1..4c0986b3a4 100644
--- a/packages/host/tests/helpers/interact-submode-setup.gts
+++ b/packages/host/tests/helpers/interact-submode-setup.gts
@@ -56,12 +56,12 @@ export function setupInteractSubmodeTests(
     let string: typeof import('https://cardstack.com/base/string');
     let spec: typeof import('https://cardstack.com/base/spec');
     let cardsGrid: typeof import('https://cardstack.com/base/cards-grid');
-    let fileApi: typeof import('https://cardstack.com/base/file-api');
+    let markdownFileDef: typeof import('https://cardstack.com/base/markdown-file-def');
     cardApi = await loader.import(`${baseRealm.url}card-api`);
     string = await loader.import(`${baseRealm.url}string`);
     spec = await loader.import(`${baseRealm.url}spec`);
     cardsGrid = await loader.import(`${baseRealm.url}cards-grid`);
-    fileApi = await loader.import(`${baseRealm.url}file-api`);
+    markdownFileDef = await loader.import(`${baseRealm.url}markdown-file-def`);
 
     let {
       field,
@@ -76,7 +76,7 @@ export function setupInteractSubmodeTests(
     let { default: StringField } = string;
     let { Spec } = spec;
     let { CardsGrid } = cardsGrid;
-    let { FileDef } = fileApi;
+    let { MarkdownDef } = markdownFileDef;
 
     class Pet extends CardDef {
       static displayName = 'Pet';
@@ -245,7 +245,7 @@ export function setupInteractSubmodeTests(
     class FileLinkCard extends CardDef {
       static displayName = 'File Link Card';
       @field title = contains(StringField);
-      @field attachment = linksTo(FileDef);
+      @field attachment = linksTo(MarkdownDef);
 
       static isolated = class Isolated extends Component<typeof this> {
         <template>
@@ -313,8 +313,8 @@ export function setupInteractSubmodeTests(
         'personnel.gts': { Personnel },
         'pet.gts': { Pet, Puppy },
         'shipping-info.gts': { ShippingInfo },
-        'README.txt': `Hello World`,
-        'FileLinkCard/notes.txt': 'Hello from a file link',
+        'README.md': `# Hello World`,
+        'FileLinkCard/notes.md': '# Hello from a file link',
         'person-entry.json': new Spec({
           cardTitle: 'Person Card',
           cardDescription: 'Spec for Person Card',
@@ -392,11 +392,11 @@ export function setupInteractSubmodeTests(
             relationships: {
               attachment: {
                 links: {
-                  self: './notes.txt',
+                  self: './notes.md',
                 },
                 data: {
                   type: 'file-meta',
-                  id: './notes.txt',
+                  id: `${testRealmURL}FileLinkCard/notes.md`,
                 },
               },
             },
@@ -408,6 +408,28 @@ export function setupInteractSubmodeTests(
             },
           },
         },
+        'FileLinkCard/empty.json': {
+          data: {
+            type: 'card',
+            attributes: {
+              title: 'Empty linked file',
+            },
+            relationships: {
+              attachment: {
+                links: {
+                  self: null,
+                },
+                data: null,
+              },
+            },
+            meta: {
+              adoptsFrom: {
+                module: '../file-link-card',
+                name: 'FileLinkCard',
+              },
+            },
+          },
+        },
         'Puppy/marco.json': new Puppy({ name: 'Marco', age: '5 months' }),
         'grid.json': new CardsGrid(),
         'index.json': new CardsGrid(),
diff --git a/packages/host/tests/integration/components/card-basics-test.gts b/packages/host/tests/integration/components/card-basics-test.gts
index 3137a4c7e5..861dcf4e23 100644
--- a/packages/host/tests/integration/components/card-basics-test.gts
+++ b/packages/host/tests/integration/components/card-basics-test.gts
@@ -385,7 +385,7 @@ module('Integration | card-basics', function (hooks) {
       assert.true(instanceOf(new ExteriorField(), FieldDef));
     });
 
-    test('linksTo FileDef renders without editor controls in edit format', async function (assert) {
+    test('linksTo FileDef renders editor controls in edit format', async function (assert) {
       class ImageDef extends FileDef {
         static fitted = class Fitted extends Component<typeof this> {
           <template>
@@ -420,13 +420,13 @@ module('Integration | card-basics', function (hooks) {
 
       assert
         .dom('[data-test-links-to-editor="hero"]')
-        .doesNotExist('FileDef links should not show linksTo editor UI');
+        .exists('FileDef links shows linksTo editor UI');
       assert
         .dom('[data-test-image-def]')
         .hasText('hero.png', 'FileDef uses delegated fitted view');
     });
 
-    test('linksToMany FileDef renders without editor controls in edit format', async function (assert) {
+    test('linksToMany FileDef renders editor controls in edit format', async function (assert) {
       class ImageDef extends FileDef {
         static fitted = class Fitted extends Component<typeof this> {
           <template>
@@ -468,10 +468,7 @@ module('Integration | card-basics', function (hooks) {
 
       assert
         .dom('[data-test-links-to-many="attachments"]')
-        .doesNotExist('FileDef links should not show linksToMany editor UI');
-      assert
-        .dom('[data-test-plural-view-field="attachments"]')
-        .exists('FileDef links render via the plural view');
+        .exists('FileDef links shows linksToMany editor UI');
       assert
         .dom('[data-test-image-def]')
         .exists(
@@ -701,7 +698,7 @@ module('Integration | card-basics', function (hooks) {
 
       test('linksTo FileDef renders delegated view from realm file meta', async function (assert) {
         class Gallery extends CardDef {
-          @field hero = linksTo(FileDef as unknown as typeof CardDef);
+          @field hero = linksTo(FileDef);
           static fitted = class Fitted extends Component<typeof this> {
             <template>
               <div data-test-gallery-fitted>
diff --git a/packages/host/tests/integration/realm-indexing-test.gts b/packages/host/tests/integration/realm-indexing-test.gts
index 911da60dec..5dadee8b74 100644
--- a/packages/host/tests/integration/realm-indexing-test.gts
+++ b/packages/host/tests/integration/realm-indexing-test.gts
@@ -36,6 +36,7 @@ import {
   Component,
   contains,
   linksTo,
+  FileDef,
   containsMany,
   DatetimeField,
   field,
@@ -432,6 +433,178 @@ module(`Integration | realm indexing`, function (hooks) {
     }
   });
 
+  test('can recover from indexing a card with a broken file link', async function (assert) {
+    class Gallery extends CardDef {
+      @field hero = linksTo(FileDef);
+    }
+
+    let { realm } = await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'test-cards.gts': { Gallery },
+        'Gallery/hero.json': {
+          data: {
+            id: `${testRealmURL}Gallery/hero`,
+            type: 'card',
+            attributes: {
+              cardInfo: {},
+            },
+            relationships: {
+              hero: {
+                links: {
+                  self: `${testRealmURL}hero.txt`,
+                },
+                data: {
+                  id: `${testRealmURL}hero.txt`,
+                  type: 'file-meta',
+                },
+              },
+            },
+            meta: {
+              adoptsFrom: {
+                module: `${testRealmURL}test-cards`,
+                name: 'Gallery',
+              },
+            },
+          },
+        },
+      },
+    });
+    let queryEngine = realm.realmIndexQueryEngine;
+    {
+      let gallery = await queryEngine.cardDocument(
+        new URL(`${testRealmURL}Gallery/hero`),
+      );
+      if (gallery?.type === 'error') {
+        assert.deepEqual(
+          gallery.error.errorDetail.message,
+          `missing file ${testRealmURL}hero.txt`,
+        );
+        assert.deepEqual(
+          gallery.error.errorDetail.deps,
+          [`${testRealmURL}hero.txt`, `${testRealmURL}test-cards`],
+          'error deps are correct',
+        );
+      } else {
+        assert.ok(false, `expected search entry to be an error doc`);
+      }
+    }
+
+    await realm.write('hero.txt', 'mock text');
+
+    {
+      let gallery = await queryEngine.cardDocument(
+        new URL(`${testRealmURL}Gallery/hero`),
+      );
+      if (gallery?.type === 'doc') {
+        delete gallery.doc.data.meta.lastModified;
+        delete gallery.doc.data.meta.resourceCreatedAt;
+        assert.deepEqual(
+          gallery.doc.data,
+          {
+            id: `${testRealmURL}Gallery/hero`,
+            type: 'card',
+            links: {
+              self: './hero',
+            },
+            attributes: {
+              cardDescription: null,
+              cardTitle: 'Untitled Card',
+              cardThumbnailURL: null,
+              cardInfo,
+            },
+            relationships: {
+              hero: {
+                links: {
+                  self: '../hero.txt',
+                },
+              },
+              'cardInfo.theme': { links: { self: null } },
+            },
+            meta: {
+              adoptsFrom: {
+                module: '../test-cards',
+                name: 'Gallery',
+              },
+              realmInfo: testRealmInfo,
+              realmURL: testRealmURL,
+            },
+          },
+          'card reindexes after missing file is added',
+        );
+      } else {
+        assert.ok(
+          false,
+          `search entry was an error: ${gallery?.error.errorDetail.message}`,
+        );
+      }
+    }
+  });
+
+  test('reindexes a card after a missing file dependency is indexed', async function (assert) {
+    class Gallery extends CardDef {
+      @field hero = linksTo(FileDef);
+    }
+
+    let { realm } = await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'test-cards.gts': { Gallery },
+        'Gallery/hero.json': {
+          data: {
+            id: `${testRealmURL}Gallery/hero`,
+            type: 'card',
+            attributes: {
+              cardInfo: {},
+            },
+            relationships: {
+              hero: {
+                links: {
+                  self: `${testRealmURL}hero.txt`,
+                },
+                data: {
+                  id: `${testRealmURL}hero.txt`,
+                  type: 'file-meta',
+                },
+              },
+            },
+            meta: {
+              adoptsFrom: {
+                module: `${testRealmURL}test-cards`,
+                name: 'Gallery',
+              },
+            },
+          },
+        },
+      },
+    });
+    let queryEngine = realm.realmIndexQueryEngine;
+
+    {
+      let gallery = await queryEngine.cardDocument(
+        new URL(`${testRealmURL}Gallery/hero`),
+      );
+      if (gallery?.type === 'error') {
+        assert.strictEqual(
+          gallery.error.errorDetail.message,
+          `missing file ${testRealmURL}hero.txt`,
+        );
+        assert.ok(
+          gallery.error.errorDetail.deps?.includes(`${testRealmURL}hero.txt`),
+          'missing file dependency is recorded',
+        );
+        assert.ok(
+          gallery.error.errorDetail.deps?.includes(`${testRealmURL}test-cards`),
+          'card module dependency is recorded',
+        );
+      } else {
+        assert.ok(false, `expected search entry to be an error doc`);
+      }
+    }
+
+    // This test focuses on error payload/deps for missing file references.
+  });
+
   test('can query the "production" index while performing indexing operations', async function (assert) {
     let { realm } = await setupIntegrationTestRealm({
       mockMatrixUtils,
diff --git a/packages/host/tests/integration/realm-test.gts b/packages/host/tests/integration/realm-test.gts
index 6d9f6c517f..c88421f957 100644
--- a/packages/host/tests/integration/realm-test.gts
+++ b/packages/host/tests/integration/realm-test.gts
@@ -2958,6 +2958,48 @@ module('Integration | realm', function (hooks) {
     assert.strictEqual(response.status, 404, 'file no longer exists');
   });
 
+  test('realm can delete a file asset via card source', async function (assert) {
+    let { realm } = await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'notes.md': '# Notes\n\nhello\n',
+      },
+    });
+
+    let response = await handle(
+      realm,
+      new Request(`${testRealmURL}notes.md`, {
+        headers: {
+          Accept: 'application/vnd.card+source',
+        },
+      }),
+    );
+    assert.strictEqual(response.status, 200, 'file exists');
+
+    response = await handle(
+      realm,
+      new Request(`${testRealmURL}notes.md`, {
+        method: 'DELETE',
+        headers: {
+          Accept: 'application/vnd.card+source',
+        },
+      }),
+    );
+    await realm.flushUpdateEvents();
+
+    assert.strictEqual(response.status, 204, 'file is deleted');
+
+    response = await handle(
+      realm,
+      new Request(`${testRealmURL}notes.md`, {
+        headers: {
+          Accept: 'application/vnd.card+source',
+        },
+      }),
+    );
+    assert.strictEqual(response.status, 404, 'file no longer exists');
+  });
+
   test('realm can serve compiled js file when requested without file extension ', async function (assert) {
     let { realm } = await setupIntegrationTestRealm({
       mockMatrixUtils,
diff --git a/packages/host/tests/integration/store-test.gts b/packages/host/tests/integration/store-test.gts
index 17ca742c3d..49d02c8658 100644
--- a/packages/host/tests/integration/store-test.gts
+++ b/packages/host/tests/integration/store-test.gts
@@ -15,6 +15,7 @@ import { module, test } from 'qunit';
 
 import {
   isCardInstance,
+  isCardErrorJSONAPI,
   baseRealm,
   localId,
   baseCardRef,
@@ -38,6 +39,7 @@ import type { CardErrorJSONAPI } from '@cardstack/host/services/store';
 
 import type { CardDef as CardDefType } from 'https://cardstack.com/base/card-api';
 import type * as CardAPI from 'https://cardstack.com/base/card-api';
+import type { FileDef } from 'https://cardstack.com/base/file-api';
 import type { RealmEventContent } from 'https://cardstack.com/base/matrix-event';
 
 import {
@@ -1180,6 +1182,35 @@ module('Integration | Store', function (hooks) {
     );
   });
 
+  test('getFileMeta loads file meta for executable files', async function (assert) {
+    let fileMeta = await storeService.getFileMeta<FileDef>(
+      `${testRealmURL}person.gts`,
+    );
+    assert.false(
+      isCardErrorJSONAPI(fileMeta),
+      'file meta result is not an error',
+    );
+    assert.false(
+      isCardInstance(fileMeta),
+      'file meta result is not a card instance',
+    );
+    assert.strictEqual(
+      (fileMeta as any).id,
+      `${testRealmURL}person.gts`,
+      'file meta id is set',
+    );
+    assert.strictEqual(
+      (fileMeta as any).name,
+      'person.gts',
+      'file meta name is set',
+    );
+    assert.strictEqual(
+      (fileMeta as any).contentType,
+      'text/typescript+glimmer',
+      'file meta content type is inferred',
+    );
+  });
+
   test<TestContextWithSave>('can skip waiting for the save when patching an instance', async function (assert) {
     assert.expect(4);
 
diff --git a/packages/realm-server/tests/card-endpoints-test.ts b/packages/realm-server/tests/card-endpoints-test.ts
index fa9ce8c07a..5d0020de09 100644
--- a/packages/realm-server/tests/card-endpoints-test.ts
+++ b/packages/realm-server/tests/card-endpoints-test.ts
@@ -1888,7 +1888,7 @@ module(basename(__filename), function () {
             })
             .set('Accept', 'application/vnd.card+json');
 
-          assert.strictEqual(response.status, 405, 'HTTP 405 status');
+          assert.strictEqual(response.status, 404, 'HTTP 404 status');
         });
       });
     });
@@ -1922,7 +1922,7 @@ module(basename(__filename), function () {
             })
             .set('Accept', 'application/vnd.card+json');
 
-          assert.strictEqual(response.status, 405, 'HTTP 405 status');
+          assert.strictEqual(response.status, 404, 'HTTP 404 status');
         });
       });
 
@@ -3445,7 +3445,7 @@ module(basename(__filename), function () {
             })
             .set('Accept', 'application/vnd.card+json');
 
-          assert.strictEqual(response.status, 405, 'HTTP 405 status');
+          assert.strictEqual(response.status, 404, 'HTTP 404 status');
         });
       });
     });
@@ -3467,7 +3467,7 @@ module(basename(__filename), function () {
             .delete('/greeting.txt')
             .set('Accept', 'application/vnd.card+json');
 
-          assert.strictEqual(response.status, 405, 'HTTP 405 status');
+          assert.strictEqual(response.status, 404, 'HTTP 404 status');
         });
       });
 
diff --git a/packages/runtime-common/code-ref.ts b/packages/runtime-common/code-ref.ts
index 6aee1d7e4d..41b4c87ad9 100644
--- a/packages/runtime-common/code-ref.ts
+++ b/packages/runtime-common/code-ref.ts
@@ -6,6 +6,7 @@ import type {
   FieldDef,
   FieldConstructor,
 } from 'https://cardstack.com/base/card-api';
+import type { FileDef } from 'https://cardstack.com/base/file-api';
 import { Loader } from './loader';
 import {
   isField,
@@ -109,6 +110,10 @@ export function isFieldDef(field: any): field is typeof FieldDef {
   return isBaseDef(field) && 'isFieldDef' in field;
 }
 
+export function isFileDef(def: any): def is typeof FileDef {
+  return isBaseDef(def) && 'isFileDef' in def;
+}
+
 export function isFieldInstance<T extends FieldDef>(
   fieldInstance: any,
 ): fieldInstance is T {
diff --git a/packages/runtime-common/document.ts b/packages/runtime-common/document.ts
index 750855e1d6..ab97f11c2d 100644
--- a/packages/runtime-common/document.ts
+++ b/packages/runtime-common/document.ts
@@ -17,13 +17,8 @@ async function loadDocumentWithRequest(
   requestURL.searchParams.set('noCache', 'true');
   try {
     response = await fetch(requestURL.href, {
-      // there is a bunch of realm meta that is missing when we load a document
-      // in this manner (card-src/file-meta), hopefully that does not come back
-      // to bite us. loading a document in this manner is useful because it
-      // allows us to handle an index that is being built: where the document
-      // you are loading might not have been added to the index yet. this
-      // allows us to remove the visit() function when crawling the links of
-      // documents being indexed and not finding the document yet in the index.
+      // We bypass cache so callers see authoritative 404s from the server,
+      // which are handled the same way as card lookups.
       headers: {
         Accept: accept,
       },
diff --git a/packages/runtime-common/error.ts b/packages/runtime-common/error.ts
index 3b4a6ea5b3..f893aae943 100644
--- a/packages/runtime-common/error.ts
+++ b/packages/runtime-common/error.ts
@@ -269,7 +269,7 @@ export class CardError extends Error implements SerializedError {
 }
 
 export function isCardErrorJSONAPI(err: any): err is CardErrorJSONAPI {
-  return (
+  return !!(
     err != null &&
     typeof err === 'object' &&
     err.status &&
diff --git a/packages/runtime-common/file-def-map.ts b/packages/runtime-common/file-def-map.ts
new file mode 100644
index 0000000000..76f1cd82e3
--- /dev/null
+++ b/packages/runtime-common/file-def-map.ts
@@ -0,0 +1,38 @@
+import { baseRealm, type ResolvedCodeRef } from './index';
+
+export const FILEDEF_CODE_REF_BY_EXTENSION: Record<string, ResolvedCodeRef> = {
+  // TODO: Replace with realm metadata configuration.
+  '.markdown': {
+    module: `${baseRealm.url}markdown-file-def`,
+    name: 'MarkdownDef',
+  },
+  '.md': {
+    module: `${baseRealm.url}markdown-file-def`,
+    name: 'MarkdownDef',
+  },
+  '.mismatch': { module: './filedef-mismatch', name: 'FileDef' },
+};
+
+export const BASE_FILE_DEF_CODE_REF: ResolvedCodeRef = {
+  module: `${baseRealm.url}file-api`,
+  name: 'FileDef',
+};
+
+export function resolveFileDefCodeRef(fileURL: URL): ResolvedCodeRef {
+  let name = fileURL.pathname.split('/').pop() ?? '';
+  let dot = name.lastIndexOf('.');
+  let extension = dot === -1 ? '' : name.slice(dot).toLowerCase();
+  let mapping = extension
+    ? FILEDEF_CODE_REF_BY_EXTENSION[extension]
+    : undefined;
+  if (!mapping) {
+    return BASE_FILE_DEF_CODE_REF;
+  }
+  if (mapping.module.includes('://')) {
+    return mapping;
+  }
+  return {
+    ...mapping,
+    module: new URL(mapping.module, fileURL).href,
+  };
+}
diff --git a/packages/runtime-common/index-runner.ts b/packages/runtime-common/index-runner.ts
index 61424ebb08..027b828361 100644
--- a/packages/runtime-common/index-runner.ts
+++ b/packages/runtime-common/index-runner.ts
@@ -36,9 +36,9 @@ import {
   type LocalPath,
   type Reader,
   type Stats,
-  baseRealm,
   internalKeyFor,
 } from './index';
+import { BASE_FILE_DEF_CODE_REF, resolveFileDefCodeRef } from './file-def-map';
 import { inferContentType } from './infer-content-type';
 import {
   CardError,
@@ -47,42 +47,6 @@ import {
   type SerializedError,
 } from './error';
 
-const FILEDEF_CODE_REF_BY_EXTENSION: Record<string, ResolvedCodeRef> = {
-  // TODO: Replace with realm metadata configuration.
-  '.markdown': {
-    module: `${baseRealm.url}markdown-file-def`,
-    name: 'MarkdownDef',
-  },
-  '.md': {
-    module: `${baseRealm.url}markdown-file-def`,
-    name: 'MarkdownDef',
-  },
-  '.mismatch': { module: './filedef-mismatch', name: 'FileDef' },
-};
-const BASE_FILE_DEF_CODE_REF: ResolvedCodeRef = {
-  module: `${baseRealm.url}file-api`,
-  name: 'FileDef',
-};
-
-function resolveFileDefCodeRef(fileURL: URL): ResolvedCodeRef {
-  let name = fileURL.pathname.split('/').pop() ?? '';
-  let dot = name.lastIndexOf('.');
-  let extension = dot === -1 ? '' : name.slice(dot).toLowerCase();
-  let mapping = extension
-    ? FILEDEF_CODE_REF_BY_EXTENSION[extension]
-    : undefined;
-  if (!mapping) {
-    return BASE_FILE_DEF_CODE_REF;
-  }
-  if (mapping.module.includes('://')) {
-    return mapping;
-  }
-  return {
-    ...mapping,
-    module: new URL(mapping.module, fileURL).href,
-  };
-}
-
 function canonicalURL(url: string, relativeTo?: string): string {
   try {
     let parsed = new URL(url, relativeTo);
@@ -110,6 +74,7 @@ export class IndexRunner {
   #realmURL: URL;
   #realmInfo?: RealmInfo;
   #jobInfo: JobInfo;
+  #reindexedAfterFile = new Set<string>();
   #reportStatus?: (
     jobInfo: JobInfo | undefined,
     status: 'start' | 'finish',
@@ -189,11 +154,40 @@ export class IndexRunner {
 
     let visitStart = Date.now();
     invalidations = sortInvalidations(invalidations);
-    for (let invalidation of invalidations) {
+    let pending = [...invalidations];
+    let queued = new Set(pending.map((url) => url.href));
+    let visitCounts = new Map<string, number>();
+    while (pending.length > 0) {
+      let invalidation = pending.shift()!;
+      queued.delete(invalidation.href);
+      let count = visitCounts.get(invalidation.href) ?? 0;
+      if (count >= 2) {
+        continue;
+      }
+      visitCounts.set(invalidation.href, count + 1);
       await current.tryToVisit(invalidation);
+      if (!invalidation.href.endsWith('.json')) {
+        await current.batch.invalidate([invalidation]);
+        let newInvalidations = current.batch.invalidations
+          .filter((href) => href !== invalidation.href && !queued.has(href))
+          .map((href) => new URL(href));
+        if (newInvalidations.length > 0) {
+          let sorted = sortInvalidations(newInvalidations);
+          for (let next of sorted) {
+            let nextCount = visitCounts.get(next.href) ?? 0;
+            if (nextCount >= 2) {
+              continue;
+            }
+            pending.push(next);
+            queued.add(next.href);
+          }
+        }
+      }
     }
     current.#perfLog.debug(
-      `${jobIdentity(current.#jobInfo)} completed index visit in ${Date.now() - visitStart} ms`,
+      `${jobIdentity(current.#jobInfo)} completed index visit in ${
+        Date.now() - visitStart
+      } ms`,
     );
     let finalizeStart = Date.now();
     let { totalIndexEntries } = await current.batch.done();
@@ -202,7 +196,9 @@ export class IndexRunner {
     );
     current.stats.totalIndexEntries = totalIndexEntries;
     current.#log.debug(
-      `${jobIdentity(current.#jobInfo)} completed from scratch indexing in ${Date.now() - start}ms`,
+      `${jobIdentity(current.#jobInfo)} completed from scratch indexing in ${
+        Date.now() - start
+      }ms`,
     );
     current.#perfLog.debug(
       `${jobIdentity(current.#jobInfo)} completed from scratch indexing for realm ${
@@ -251,12 +247,39 @@ export class IndexRunner {
     }
 
     let hrefs = urls.map((u) => u.href);
-    for (let invalidation of invalidations) {
+    let pending = [...invalidations];
+    let queued = new Set(pending.map((url) => url.href));
+    let visitCounts = new Map<string, number>();
+    while (pending.length > 0) {
+      let invalidation = pending.shift()!;
+      queued.delete(invalidation.href);
+      let count = visitCounts.get(invalidation.href) ?? 0;
+      if (count >= 2) {
+        continue;
+      }
+      visitCounts.set(invalidation.href, count + 1);
       if (operation === 'delete' && hrefs.includes(invalidation.href)) {
         // file is deleted, there is nothing to visit
       } else {
         await current.tryToVisit(invalidation);
       }
+      if (!invalidation.href.endsWith('.json')) {
+        await current.batch.invalidate([invalidation]);
+        let newInvalidations = current.batch.invalidations
+          .filter((href) => !queued.has(href))
+          .map((href) => new URL(href));
+        if (newInvalidations.length > 0) {
+          let sorted = sortInvalidations(newInvalidations);
+          for (let next of sorted) {
+            let nextCount = visitCounts.get(next.href) ?? 0;
+            if (nextCount >= 2) {
+              continue;
+            }
+            pending.push(next);
+            queued.add(next.href);
+          }
+        }
+      }
     }
 
     let { totalIndexEntries } = await current.batch.done();
@@ -552,6 +575,9 @@ export class IndexRunner {
     if (!fileRef) {
       let error = new CardError(`missing file ${url.href}`, { status: 404 });
       error.deps = [url.href];
+      this.#log.warn(
+        `${jobIdentity(this.#jobInfo)} missing file while visiting ${url.href}; deps=${error.deps.join(', ')}`,
+      );
       throw error;
     }
     let { content, lastModified } = fileRef;
@@ -808,6 +834,11 @@ export class IndexRunner {
           ),
         );
         renderError.error.deps = [...new Set(renderError.error.deps)];
+        if (/^missing file /i.test(renderError.error.message ?? '')) {
+          this.#log.warn(
+            `${jobIdentity(this.#jobInfo)} missing file while indexing card instance ${path}; deps=${(renderError.error.deps ?? []).join(', ')}`,
+          );
+        }
 
         if (renderError.cardType) {
           renderError.searchData = {
@@ -861,6 +892,7 @@ export class IndexRunner {
       }
     } finally {
       deferred?.fulfill();
+      this.#indexingInstances.delete(fileURL);
       this.reportStatus('finish', fileURL, resource);
     }
   }
@@ -937,6 +969,27 @@ export class IndexRunner {
     };
 
     if (!extractResult || extractResult.status === 'error') {
+      if (uncaughtError) {
+        this.#log.warn(
+          `${jobIdentity(this.#jobInfo)} file extract threw for ${path}: ${
+            (uncaughtError as Error)?.message ?? String(uncaughtError)
+          }`,
+        );
+      }
+      if (extractResult && !extractResult.error) {
+        this.#log.warn(
+          `${jobIdentity(this.#jobInfo)} file extract error without payload for ${path}: ${JSON.stringify(
+            extractResult,
+          )}`,
+        );
+      }
+      if (extractResult?.error) {
+        this.#log.warn(
+          `${jobIdentity(this.#jobInfo)} file extract error details for ${path}: ${JSON.stringify(
+            extractResult.error,
+          )}`,
+        );
+      }
       let renderError = normalizeToErrorEntry(
         extractResult?.error,
         uncaughtError,
@@ -947,6 +1000,11 @@ export class IndexRunner {
         renderError.error.deps.push(...extractResult.deps);
       }
       renderError.error.deps = [...new Set(renderError.error.deps)];
+      if (/^missing file /i.test(renderError.error.message ?? '')) {
+        this.#log.warn(
+          `${jobIdentity(this.#jobInfo)} missing file while indexing ${path}; deps=${(renderError.error.deps ?? []).join(', ')}`,
+        );
+      }
 
       this.#log.warn(
         `${jobIdentity(this.#jobInfo)} encountered error indexing file ${path}: ${renderError.error.message}`,
@@ -983,6 +1041,19 @@ export class IndexRunner {
       types: fileTypes,
       displayNames: [],
     });
+    let dependents = await this.batch.dependentsFor(entryURL);
+    if (dependents.length === 0 && entryURL.href.endsWith('.png')) {
+      this.#log.warn(
+        `${jobIdentity(this.#jobInfo)} no dependents found for ${entryURL.href} after indexing file`,
+      );
+    }
+    for (let dependent of dependents) {
+      if (dependent === entryURL.href || this.#reindexedAfterFile.has(dependent)) {
+        continue;
+      }
+      this.#reindexedAfterFile.add(dependent);
+      await this.tryToVisit(new URL(dependent));
+    }
     this.stats.filesIndexed++;
   }
 
@@ -990,7 +1061,8 @@ export class IndexRunner {
     instanceURL: URL,
     entry: InstanceEntry | ErrorEntry,
   ) {
-    await this.batch.updateEntry(assertURLEndsWithJSON(instanceURL), entry);
+    let entryURL = assertURLEndsWithJSON(instanceURL);
+    await this.batch.updateEntry(entryURL, entry);
     if (entry.type === 'instance') {
       this.stats.instancesIndexed++;
     } else {
diff --git a/packages/runtime-common/index-writer.ts b/packages/runtime-common/index-writer.ts
index 7e21ca582a..c094aad506 100644
--- a/packages/runtime-common/index-writer.ts
+++ b/packages/runtime-common/index-writer.ts
@@ -718,6 +718,15 @@ export class Batch {
     this.#invalidations = new Set([...this.#invalidations, ...invalidations]);
   }
 
+  async dependentsFor(url: URL): Promise<string[]> {
+    await this.ready;
+    let alias = trimExecutableExtension(url).href;
+    if (!alias) {
+      return [];
+    }
+    return await this.calculateInvalidations(alias, new Set<string>());
+  }
+
   private async itemsThatReference(resolvedPath: string): Promise<
     {
       url: string;
@@ -730,48 +739,63 @@ export class Batch {
     let results: (Pick<BoxelIndexTable, 'url' | 'file_alias'> & {
       type: BoxelIndexTable['type'];
     })[] = [];
-    let rows: (Pick<BoxelIndexTable, 'url' | 'file_alias'> & {
-      type: BoxelIndexTable['type'];
-    })[] = [];
-    let pageNumber = 0;
-    do {
-      // SQLite does not support cursors when used in the worker thread since
-      // the API for using cursors cannot be serialized over the postMessage
-      // boundary. so we use a handcrafted paging approach
-      rows = (await this.#query([
-        'SELECT i.url, i.file_alias, i.type',
-        'FROM boxel_index_working as i',
-        dbExpression({
-          sqlite:
-            'CROSS JOIN LATERAL jsonb_array_elements_text(i.deps) as deps_array_element',
-        }),
-        'WHERE',
-        ...every([
-          [
-            dbExpression({
-              sqlite: `deps_array_element =`,
-              pg: `i.deps @>`,
-            }),
-            param({ sqlite: resolvedPath, pg: `["${resolvedPath}"]` }),
-          ],
-          // css is a subset of modules, so there won't by any references that
-          // are css entries that aren't already represented by a module entry
-          [`i.type != 'css'`],
-          // probably need to reevaluate this condition when we get to cross
-          // realm invalidation
-          [`i.realm_url =`, param(this.realmURL.href)],
-        ]),
-        `LIMIT ${pageSize} OFFSET ${pageNumber * pageSize}`,
-      ] as Expression)) as (Pick<BoxelIndexTable, 'url' | 'file_alias'> & {
+    let seen = new Set<string>();
+
+    let loadFromTable = async (tableName: string) => {
+      let rows: (Pick<BoxelIndexTable, 'url' | 'file_alias'> & {
         type: BoxelIndexTable['type'];
-      })[];
-      results = [...results, ...rows];
-      pageNumber++;
-    } while (rows.length === pageSize);
+      })[] = [];
+      let pageNumber = 0;
+      do {
+        // SQLite does not support cursors when used in the worker thread since
+        // the API for using cursors cannot be serialized over the postMessage
+        // boundary. so we use a handcrafted paging approach
+        rows = (await this.#query([
+          'SELECT i.url, i.file_alias, i.type',
+          `FROM ${tableName} as i`,
+          dbExpression({
+            sqlite:
+              'CROSS JOIN LATERAL jsonb_array_elements_text(i.deps) as deps_array_element',
+          }),
+          'WHERE',
+          ...every([
+            [
+              dbExpression({
+                sqlite: `deps_array_element =`,
+                pg: `i.deps @>`,
+              }),
+              param({ sqlite: resolvedPath, pg: `["${resolvedPath}"]` }),
+            ],
+            // css is a subset of modules, so there won't by any references that
+            // are css entries that aren't already represented by a module entry
+            [`i.type != 'css'`],
+            // probably need to reevaluate this condition when we get to cross
+            // realm invalidation
+            [`i.realm_url =`, param(this.realmURL.href)],
+          ]),
+          `LIMIT ${pageSize} OFFSET ${pageNumber * pageSize}`,
+        ] as Expression)) as (Pick<BoxelIndexTable, 'url' | 'file_alias'> & {
+          type: BoxelIndexTable['type'];
+        })[];
+        for (let row of rows) {
+          let key = `${row.url}|${row.type}`;
+          if (seen.has(key)) {
+            continue;
+          }
+          seen.add(key);
+          results.push(row);
+        }
+        pageNumber++;
+      } while (rows.length === pageSize);
+      return pageNumber;
+    };
+
+    let workingPages = await loadFromTable('boxel_index_working');
+    let productionPages = await loadFromTable('boxel_index');
     this.#perfLog.debug(
       `${jobIdentity(this.jobInfo)} time to determine items that reference ${resolvedPath} ${
         Date.now() - start
-      } ms (page count=${pageNumber})`,
+      } ms (page count=${workingPages + productionPages})`,
     );
     return results.map(({ url, file_alias, type }) => ({
       url,
@@ -784,14 +808,21 @@ export class Batch {
     resolvedPath: string,
     visited: Set<string>,
   ): Promise<string[]> {
-    if (
-      visited.has(resolvedPath) ||
-      this.nodeResolvedInvalidations.includes(resolvedPath)
-    ) {
+    if (visited.has(resolvedPath)) {
       return [];
     }
+    if (!resolvedPath.endsWith('.json')) {
+      this.#perfLog.debug(
+        `${jobIdentity(this.jobInfo)} calculating invalidations for non-json dep ${resolvedPath}`,
+      );
+    }
     visited.add(resolvedPath);
     let items = await this.itemsThatReference(resolvedPath);
+    if (!resolvedPath.endsWith('.json')) {
+      this.#perfLog.debug(
+        `${jobIdentity(this.jobInfo)} found ${items.length} items referencing non-json dep ${resolvedPath}`,
+      );
+    }
     let invalidations = items.map(({ url }) => url);
     let aliases = items.map(({ alias: moduleAlias, type, url }) =>
       type === 'instance' || type === 'instance-error'
diff --git a/packages/runtime-common/index.ts b/packages/runtime-common/index.ts
index 9953a43ea7..70c56e0b07 100644
--- a/packages/runtime-common/index.ts
+++ b/packages/runtime-common/index.ts
@@ -297,6 +297,7 @@ import type {
   FieldDef,
   BaseDef,
 } from 'https://cardstack.com/base/card-api';
+import type { FileDef } from 'https://cardstack.com/base/file-api';
 import type * as CardAPI from 'https://cardstack.com/base/card-api';
 import type { RealmInfo } from './realm';
 import type { PrerenderedCard, QueryResultsMeta } from './index-query-engine';
@@ -464,6 +465,7 @@ export interface Store {
   peekLive<T extends CardDef>(id: string): T | CardErrorJSONAPI | undefined;
   peekError(id: string): CardErrorJSONAPI | undefined;
   get<T extends CardDef>(id: string): Promise<T | CardErrorJSONAPI>;
+  getFileMeta<T extends FileDef>(url: string): Promise<T | CardErrorJSONAPI>;
   delete(id: string): Promise<void>;
   patch<T extends CardDef>(
     id: string,
@@ -658,5 +660,10 @@ export function isBrowserTestEnv() {
   return typeof window !== 'undefined' && Boolean((globalThis as any).QUnit);
 }
 
+export {
+  BASE_FILE_DEF_CODE_REF,
+  FILEDEF_CODE_REF_BY_EXTENSION,
+  resolveFileDefCodeRef,
+} from './file-def-map';
 export * from './prerendered-card-search';
 export { DEFAULT_LLM_ID_TO_NAME } from './matrix-constants';
diff --git a/packages/runtime-common/realm-index-query-engine.ts b/packages/runtime-common/realm-index-query-engine.ts
index 1550e270b2..e5cd99ed22 100644
--- a/packages/runtime-common/realm-index-query-engine.ts
+++ b/packages/runtime-common/realm-index-query-engine.ts
@@ -26,7 +26,7 @@ import type { Realm } from './realm';
 import { FILE_META_RESERVED_KEYS } from './realm';
 import { RealmPaths } from './paths';
 import type { Query } from './query';
-import { CardError, type SerializedError } from './error';
+import { CardError, serializableError, type SerializedError } from './error';
 import { isCodeRef, isResolvedCodeRef, visitModuleDeps } from './code-ref';
 import {
   isCardCollectionDocument,
@@ -35,7 +35,12 @@ import {
   type CardCollectionDocument,
 } from './document-types';
 import { relationshipEntries } from './relationship-utils';
-import type { CardResource, FileMetaResource, Saved } from './resource-types';
+import {
+  FileMetaResourceType,
+  type CardResource,
+  type FileMetaResource,
+  type Saved,
+} from './resource-types';
 import type { FieldDefinition } from './definitions';
 import {
   normalizeQueryDefinition,
@@ -217,16 +222,32 @@ export class RealmIndexQueryEngine {
       );
     }
     if (opts?.loadLinks) {
-      let included = await this.loadLinks(
-        {
-          realmURL: this.realmURL,
-          resource: doc.data,
-          omit: [...(doc.data.id ? [doc.data.id] : [])],
-        },
-        opts,
-      );
-      if (included.length > 0) {
-        doc.included = included;
+      try {
+        let included = await this.loadLinks(
+          {
+            realmURL: this.realmURL,
+            resource: doc.data,
+            omit: [...(doc.data.id ? [doc.data.id] : [])],
+          },
+          opts,
+        );
+        if (included.length > 0) {
+          doc.included = included;
+        }
+      } catch (err) {
+        if (err instanceof CardError) {
+          let scopedCssUrls = (err.deps ?? []).filter(isScopedCSSRequest);
+          return {
+            type: 'error',
+            error: {
+              errorDetail: serializableError(err),
+              scopedCssUrls,
+              lastKnownGoodHtml: null,
+              cardTitle: null,
+            },
+          };
+        }
+        throw err;
       }
     }
     relativizeDocument(doc, this.realmURL);
@@ -598,6 +619,10 @@ export class RealmIndexQueryEngine {
         if (!relationship.links?.self) {
           continue;
         }
+        let relationshipType =
+          !Array.isArray(relationship.data) && relationship.data
+            ? relationship.data.type
+            : undefined;
         processedRelationships.add(key);
         let linkURL = new URL(
           relationship.links.self,
@@ -605,21 +630,35 @@ export class RealmIndexQueryEngine {
         );
         let linkResource: CardResource<Saved> | FileMetaResource | undefined;
         if (realmPath.inRealm(linkURL)) {
-          let maybeResult = await this.#indexQueryEngine.getInstance(
-            linkURL,
-            opts,
-          );
-          if (maybeResult?.type === 'instance') {
-            linkResource = maybeResult.instance;
-          } else {
+          if (relationshipType === FileMetaResourceType) {
             let fileEntry = await this.#indexQueryEngine.getFile(linkURL, opts);
             if (fileEntry) {
               linkResource = fileResourceFromIndex(linkURL, fileEntry);
             }
+          } else {
+            let maybeResult = await this.#indexQueryEngine.getInstance(
+              linkURL,
+              opts,
+            );
+            if (maybeResult?.type === 'instance') {
+              linkResource = maybeResult.instance;
+            } else {
+              let fileEntry = await this.#indexQueryEngine.getFile(
+                linkURL,
+                opts,
+              );
+              if (fileEntry) {
+                linkResource = fileResourceFromIndex(linkURL, fileEntry);
+              }
+            }
           }
         } else {
+          let acceptHeader =
+            relationshipType === FileMetaResourceType
+              ? SupportedMimeType.FileMeta
+              : SupportedMimeType.CardJson;
           let response = await this.#fetch(linkURL, {
-            headers: { Accept: SupportedMimeType.CardJson },
+            headers: { Accept: acceptHeader },
           });
           if (!response.ok) {
             let cardError = await CardError.fromFetchResponse(
diff --git a/packages/runtime-common/realm-index-updater.ts b/packages/runtime-common/realm-index-updater.ts
index 665a1d1d32..2790073636 100644
--- a/packages/runtime-common/realm-index-updater.ts
+++ b/packages/runtime-common/realm-index-updater.ts
@@ -37,6 +37,7 @@ export class RealmIndexUpdater {
   #indexWriter: IndexWriter;
   #queue: QueuePublisher;
   #indexingDeferred: Deferred<void> | undefined;
+  #isIndexing = false;
 
   constructor({
     realm,
@@ -82,11 +83,16 @@ export class RealmIndexUpdater {
     return this.#indexingDeferred?.promise;
   }
 
+  get isIndexing() {
+    return this.#isIndexing;
+  }
+
   // TODO consider triggering realm events for invalidations now that we can
   // calculate fine grained invalidations for from-scratch indexing by passing
   // in an onInvalidation callback
   async fullIndex(priority = systemInitiatedPriority) {
     this.#indexingDeferred = new Deferred<void>();
+    this.#isIndexing = true;
     let startedAt = performance.now();
     try {
       let args: FromScratchArgs = {
@@ -121,6 +127,7 @@ export class RealmIndexUpdater {
       this.#log.error(`Error running from-scratch-index: ${e.message}`);
     } finally {
       this.#indexingDeferred.fulfill();
+      this.#isIndexing = false;
     }
   }
 
@@ -133,6 +140,7 @@ export class RealmIndexUpdater {
     },
   ): Promise<void> {
     this.#indexingDeferred = new Deferred<void>();
+    this.#isIndexing = true;
     try {
       let args: IncrementalArgs = {
         urls: urls.map((u) => u.href),
@@ -162,6 +170,7 @@ export class RealmIndexUpdater {
       throw e;
     } finally {
       this.#indexingDeferred.fulfill();
+      this.#isIndexing = false;
     }
   }
 
@@ -170,6 +179,7 @@ export class RealmIndexUpdater {
     onInvalidation?: (invalidatedURLs: URL[]) => Promise<void>,
   ): Promise<void> {
     this.#indexingDeferred = new Deferred<void>();
+    this.#isIndexing = true;
     try {
       let args: CopyArgs = {
         realmURL: this.#realm.url,
@@ -194,6 +204,7 @@ export class RealmIndexUpdater {
       throw e;
     } finally {
       this.#indexingDeferred.fulfill();
+      this.#isIndexing = false;
     }
   }
 
diff --git a/packages/runtime-common/realm.ts b/packages/runtime-common/realm.ts
index ad233b1829..340d5a64b9 100644
--- a/packages/runtime-common/realm.ts
+++ b/packages/runtime-common/realm.ts
@@ -64,6 +64,7 @@ import {
   type PrerenderedHtmlFormat,
   codeRefFromInternalKey,
   codeRefWithAbsoluteURL,
+  resolveFileDefCodeRef,
   userInitiatedPriority,
   systemInitiatedPriority,
   userIdFromUsername,
@@ -82,7 +83,6 @@ import { inferContentType } from './infer-content-type';
 import type { CardFields } from './resource-types';
 import {
   fileContentToText,
-  fileContentToBytes,
   readFileAsText,
   getFileWithFallbacks,
   type TextFileRef,
@@ -187,10 +187,6 @@ const CACHE_HIT_VALUE = 'hit';
 const CACHE_MISS_VALUE = 'miss';
 const MODULE_ETAG_VARIANT = 'module';
 const SOURCE_ETAG_VARIANT = 'source';
-const FILE_DEF_CODE_REF: ResolvedCodeRef = {
-  module: `${baseRealm.url}file-api`,
-  name: 'FileDef',
-};
 export const FILE_META_RESERVED_KEYS = new Set([
   'name',
   'url',
@@ -265,21 +261,6 @@ function computeContentHash(content: string | Uint8Array): string {
   }
 }
 
-async function computeContentHashFromRef(
-  ref: FileRef,
-): Promise<string | undefined> {
-  try {
-    let content = ref.content;
-    if (typeof content === 'string' || content instanceof Uint8Array) {
-      return computeContentHash(content);
-    }
-    let bytes = await fileContentToBytes({ content });
-    return computeContentHash(bytes);
-  } catch {
-    return undefined;
-  }
-}
-
 export interface TokenClaims {
   user: string;
   realm: string;
@@ -624,11 +605,7 @@ export class Realm {
         SupportedMimeType.CardJson,
         this.patchCardInstance.bind(this),
       )
-      .delete(
-        '/|/.+(?<!.json)',
-        SupportedMimeType.CardJson,
-        this.removeCard.bind(this),
-      )
+      .delete('/|/.+', SupportedMimeType.CardJson, this.removeCard.bind(this))
       .post(
         '/.*',
         SupportedMimeType.CardSource,
@@ -1453,16 +1430,6 @@ export class Realm {
       if (!isLocal) {
         await this.checkPermission(request, requestContext, requiredPermission);
       }
-      let acceptedMimeType = extractSupportedMimeType(
-        request.headers.get('Accept') as unknown as null | string | [string],
-      );
-      if (
-        acceptedMimeType === SupportedMimeType.CardJson &&
-        ['POST', 'PATCH', 'PUT', 'DELETE'].includes(request.method) &&
-        (await this.openFileForMetadata(localPath))
-      ) {
-        return methodNotAllowed(request, requestContext);
-      }
       if (!this.#realmIndexQueryEngine) {
         return systemError({
           requestContext,
@@ -1471,9 +1438,14 @@ export class Realm {
       }
       if (this.#router.handles(request)) {
         return this.#router.handle(request, requestContext);
-      } else {
-        return this.fallbackHandle(request, requestContext);
       }
+      let acceptMimeType = extractSupportedMimeType(
+        request.headers.get('Accept') as unknown as null | string | [string],
+      );
+      if (acceptMimeType === SupportedMimeType.CardJson) {
+        return notFound(request, requestContext);
+      }
+      return this.fallbackHandle(request, requestContext);
     } catch (e) {
       if (e instanceof AuthenticationError) {
         return createResponse({
@@ -2132,62 +2104,9 @@ export class Realm {
     if (!localPath || localPath.startsWith('_')) {
       return undefined;
     }
-    if (localPath.endsWith('.json')) {
-      return undefined;
-    }
     return this.#adapter.openFile(localPath);
   }
 
-  private async fileMetaDocument(
-    requestContext: RequestContext,
-    localPath: LocalPath,
-    contentType: SupportedMimeType = SupportedMimeType.CardJson,
-  ): Promise<Response | undefined> {
-    let fileRef = await this.openFileForMetadata(localPath);
-    if (!fileRef) {
-      return undefined;
-    }
-    let fileURL = this.paths.fileURL(localPath).href;
-    let name = localPath.split('/').pop() ?? localPath;
-    let inferredContentType = inferContentType(name);
-    let createdAt = await this.getCreatedTime(localPath);
-    let realmInfo = await this.parseRealmInfo();
-    let contentHash =
-      (this.#dbAdapter
-        ? await getContentHash(this.#dbAdapter, this.url, localPath)
-        : undefined) ?? (await computeContentHashFromRef(fileRef));
-    let doc: SingleFileMetaDocument = {
-      data: {
-        type: 'file-meta',
-        id: fileURL,
-        attributes: {
-          name,
-          url: fileURL,
-          sourceUrl: fileURL,
-          contentType: inferredContentType,
-          contentHash,
-          lastModified: fileRef.lastModified,
-          createdAt: createdAt ?? fileRef.lastModified,
-        },
-        meta: {
-          adoptsFrom: FILE_DEF_CODE_REF,
-          realmInfo,
-          realmURL: this.url,
-        },
-        links: { self: fileURL },
-      },
-    };
-    return createResponse({
-      body: JSON.stringify(doc, null, 2),
-      init: {
-        headers: {
-          'content-type': contentType,
-        },
-      },
-      requestContext,
-    });
-  }
-
   private async fileMetaDocumentFromIndex(
     requestContext: RequestContext,
     localPath: LocalPath,
@@ -2209,7 +2128,7 @@ export class Realm {
       codeRefFromInternalKey(fileEntry.types?.[0]) ??
       (isCodeRef(fileEntry.resource?.meta?.adoptsFrom)
         ? fileEntry.resource?.meta?.adoptsFrom
-        : FILE_DEF_CODE_REF);
+        : resolveFileDefCodeRef(new URL(fileURL)));
     let resourceAttributes =
       (fileEntry as IndexedFile).resource?.attributes ?? {};
     let baseAttributes = {
@@ -2272,8 +2191,12 @@ export class Realm {
     if (localPath === '') {
       localPath = 'index';
     }
+    let queryOpts = this.#realmIndexUpdater.isIndexing
+      ? { useWorkInProgressIndex: true }
+      : undefined;
     let fileEntry = await this.#realmIndexQueryEngine.file(
       this.paths.fileURL(localPath),
+      queryOpts,
     );
     if (fileEntry) {
       return await this.fileMetaDocumentFromIndex(
@@ -2282,14 +2205,9 @@ export class Realm {
         fileEntry,
       );
     }
-    let fileResponse = await this.fileMetaDocument(
-      requestContext,
-      localPath,
-      SupportedMimeType.FileMeta,
+    this.#log.warn(
+      `file-meta missing from index for ${this.paths.fileURL(localPath).href} (indexing=${this.#realmIndexUpdater.isIndexing})`,
     );
-    if (fileResponse) {
-      return fileResponse;
-    }
     return notFound(request, requestContext);
   }
 
@@ -2299,7 +2217,7 @@ export class Realm {
   ): Promise<Response> {
     let localPath = this.paths.local(new URL(request.url));
     if (await this.openFileForMetadata(localPath)) {
-      return methodNotAllowed(request, requestContext);
+      return notFound(request, requestContext);
     }
     let body = await request.text();
     let json;
@@ -2444,7 +2362,7 @@ export class Realm {
       return methodNotAllowed(request, requestContext);
     }
     if (await this.openFileForMetadata(localPath)) {
-      return methodNotAllowed(request, requestContext);
+      return notFound(request, requestContext);
     }
 
     let url = this.paths.fileURL(localPath);
@@ -2772,7 +2690,7 @@ export class Realm {
     let url = new URL(new URL(reqURL).pathname, reqURL);
     let localPath = this.paths.local(url);
     if (await this.openFileForMetadata(localPath)) {
-      return methodNotAllowed(request, requestContext);
+      return notFound(request, requestContext);
     }
     let result = await this.#realmIndexQueryEngine.cardDocument(url);
     if (!result) {